Texas 

Instruments 

TMS34010 

Assembly Language Tools 


User’s Guide 


1 


1987 


Graphics Products 




TMS34010 

Assembly Language Tools 
User's Guide 


Texas 



IMPORTANT NOTICE 

Texas Instruments (Tl) reserves the right to make changes to or to discontinue 
any semiconductor product or service identified in this publication without 
notice. Tl advises its customers to obtain the latest version of the relevant in¬ 
formation to verify, before placing orders, that the information being relied 
upon is current. 

Tl warrants performance of its semiconductor products to current specifica¬ 
tions in accordance with Tl's standard warranty. Testing and other quality 
control techniques are utilized to the extent Tl deems necessary to support this 
warranty. Unless mandated by government requirements, specific testing of 
all parameters of each device is not necessarily performed. 

Tl assumes no liability for Tl applications assistance, customer product design, 
software performance, or infringement of patents or services described herein. 
Nor does Tl warrant or represent that license, either express or implied, is 
granted under any patent right, copyright, mask work right, or other intellec¬ 
tual property right of Tl covering or relating to any combination, machine, or 
process in which such semiconductor products or services might be or are 
used. 


Copyright © 1987, Texas Instruments Incorporated 



Contents 


Section Page 

1 Introduction 1-1 

1.1 Software Development Tools Overview .. 1-2 

1.2 Getting Started . 1-4 

1.3 Manual Organization . 1-5 

1.4 Related Documentation . 1-6 

1.5 Style and Symbol Conventions . 1-7 

2 Software Installation 2-1 

2.1 Installation for IBM/TI PCs with PC/MS-DOS . 2-2 

2.2 Installation for VAX/VMS . 2-4 

2.3 Installation for VAX/ULTRIX and VAX/System V . 2-4 

3 Introduction to Common Object File Format 3-1 

3.1 Sections. 3-2 

3.2 How the Assembler Handles Sections . 3-3 

3.2.1 Uninitialized Sections. 3-4 

3.2.2 Initialized Sections . 3-4 

3.2.3 Named Sections . 3-5 

3.2.4 Section Program Counters . 3-6 

3.2.5 An Example That Uses Sections Directives. 3-6 

3.3 How the Linker Handles Sections . 3-9 

3.3.1 Default Allocation. 3-9 

3.3.2 Placing Sections in the Memory Map . 3-12 

3.4 Relocation . 3-15 

3.5 Loading a Program . 3-16 

3.6 Symbols in a COFF File . 3-17 

3.6.1 External Symbols . 3-17 

3.6.2 The Symbol Table. 3-17 

4 Assembler Description 4-1 

4.1 Assembler Development Flow . 4-2 

4.2 Invoking the Assembler. 4-3 

4.3 Specifying Alternate Directories for Assembler Input . 4-4 

4.3.1 -i Assembler Option . 4-4 

4.3.2 Environment Variable (A—DIR) . 4-5 

4.4 Source Statement Format . 4-6 

4.4.1 Label Field . 4-6 

4.4.2 Mnemonic Field. 4-7 

4.4.3 Operand List . 4-7 

4.4.4 Comment Field . 4-7 

4.5 Constants . 4-8 

4.5.1 Binary Integers . 4-8 

4.5.2 Octal Integers . 4-8 

4.5.3 Decimal Integers . 4-9 

4.5.4 Hexadecimal Integers . 4-9 

4.5.5 XY Constants . 4-9 

4.5.6 Character Constants . 4-10 

4.5.7 Assembly-Time Constants . 4-10 


iii 












































4.6 Character Strings . 4-11 

4.7 Symbols. 4-11 

4.8 Expressions . 4-12 

4.8.1 Operators . 4-13 

4.8.2 Expression Overflow or Underflow . 4-14 

4.8.3 Well-Defined Expressions . 4-14 

4.8.4 Conditional Expressions . 4-14 

4.8.5 Relocatable Symbols and Legal Expressions . 4-14 

4.9 Source Listings . 4-16 

4.10 Cross- Reference Llstinas . 4 18 


5 Assembler Directives 5-1 

5.1 Directives Summary . 5-2 

5.2 Sections Directives . 5-4 

5.3 Directives that Initialize Constants . 5-6 

5.4 Directives that Align the Section Program Counter . 5-9 

5.5 Directives that Format the Output Listing . 5-11 

5.6 Conditional Assembly Directives . 5-12 

5.7 Directives that Reference Other Files . 5-13 

5.8 Directives Reference . 5-14 

6 Instruction Set 6-1 

6.1 Overview of Operand Formats . 6-2 

6.2 Summary Table . 6-5 

6.3 Arithmetic, Logical, and Compare Instructions. 6-22 

6.4 Move Instructions . 6-24 

6.5 Graphics Instructions . 6-26 

6.6 Program Control and Context Switching Instructions . 6-29 

6.7 Jump Instructions . 6-30 

6.8 Shift Instructions . 6-32 

6.9 XY Instructions . 6-33 

7 Macro Language 7-1 

7.1 Macro Directives Summary . 7-2 

7.2 Macro Libraries . 7-3 

7.3 Defining Macros ... 7-4 

7.4 Macro Parameters ... 7-6 

7.5 Conditional Blocks ... 7-7 

7.6 Repeatable Blocks . 7-8 

7.7 Unique Labels . 7-9 

8 Archiver Description 8-1 

8.1 Archiver Development Flow . 8-2 

8.2 Invoking the Archiver . 8-3 

8.3 Archiver Examples . 8-4 


IV 








































9 Linker Description 9-1 

9.1 Linker Development Flow . 9-2 

9.2 Invoking the Linker . 9-3 

9.3 Linker Options . 9-4 

9.3.1 Relocation Capability (-a and -r Options) . 9-4 

9.3.2 C Language Options (-c and -cr Options) . 9-6 

9.3.3 Define an Entry Point (-e symbol Option) . 9-6 

9.3.4 Set Default Fill Value (-f cc Option) .. 9-6 

9.3.5 Make All Global Symbols Static (-h Option) . 9-7 

9.3.6 Alter the Library Search Algorithm {-\dir Option/C— DIR) . 9-7 

9.3.7 Create a Map File (-m filename Option) . 9-9 

9.3.8 Name an Output Module (-o filename Option) . 9-9 

9.3.9 Specify a Quiet Run (-q Option) . 9-9 

9.3.10 Strip Symbolic Information (-s Option) . 9-10 

9.3.11 Introduce an Unresolved Symbol (-u symbol Option) . 9-10 

9.4 Linker Command Files . 9-11 

9.5 Object Libraries . 9-13 

9.6 The MEMORY Directive . 9-14 

9.6.1 Default Memory Model . 9-14 

9.6.2 MEMORY Directive Syntax . 9-14 

9.7 The SECTIONS Directive . 9-16 

9.7.1 Default Sections Configuration . 9-16 

9.7.2 SECTIONS Directive Syntax . 9-16 

9.7.3 Specifying Input Sections . 9-18 

9.7.4 Specifying the Address of Output Sections (Allocation) . 9-20 

9.7.5 Grouping Output Sections Together . 9-22 

9.8 Overlay Pages. 9-23 

9.8.1 Using the MEMORY Directive to Define Overlay Pages . 9-23 

9.8.2 Using Overlay Pages with the SECTIONS Directive . 9-24 

9.8.3 Syntax of Page Definitions . 9-25 

9.9 Default Allocation . 9-27 

9.9.1 Allocation Algorithm . 9-27 

9.9.2 General Rules for Output Sections . 9-27 

9.10 Special Section Types (DSECT, COPY, and NOLOAD) . 9-29 

9.11 Assigning Symbols at Link Time . 9-30 

9.11.1 Syntax of Assignment Statements . 9-30 

9.11.2 Assigning the SPC to a Symbol . 9-30 

9.11.3 Assignment Expressions . 9-31 

9.11.4 Symbols Defined by the Linker . 9-32 

9.12 Creating and Filling Holes . 9-33 

9.12.1 Initialized and Uninitialized Sections . 9-33 

9.12.2 Creating Holes . 9-33 

9.12.3 Filling Holes . 9-35 

9.12.4 Explicit Initialization of Uninitialized Sections . 9-36 

9.13 Partial Linking . 9-37 

9.14 Linking C Code . 9-38 

9.14.1 Runtime Initialization . 9-38 

9.14.2 Object Libraries and Runtime Support . 9-38 

9.14.3 Autoinitialization (ROM and RAM Models) . 9-38 

9.14.4 The -c and -cr Linker Options . 9-40 

9.15 Linker Example . 9-41 


v 





















































10 Object Format Converter Description 10-1 

10.1 Object Format Converter Development Flow . 10-2 

10.2 Invoking the Object Format Converter . 10-3 

10.3 Object Format Converter Examples. 10-4 

11 Simulator Description 11-1 

11.1 Simulator Development Flow. 11-2 

11.2 Invoking the Simulator . 11-3 

113 Hardware and System Requirements . 11-4 

11.4 Screen Displays. 11-5 

11.4.1 Machine-State Display . 11-5 

11.4.2 Displaying Graphics and Status Information Simultaneously . 11-9 

11.4.3 Using the HELP Function . 11-9 

11.5 Entering Commands . 11-11 

11.5.1 Command Parameters . 11-12 

11.5.2 Command Buffers. 11-13 

11.5.3 Loading and Running Code . 11-15 

11.5.4 Line Assembler . 11-16 

11.5.5 Error Reporting . 11-16 

11.6 System Simulation . 11-17 

11.6.1 Local Memory Simulation . 11-17 

11.6.2 Interrupts Simulation . 11-17 

11.6.3 Host Interface Simulation. 11-17 

11.6.4 Graphics Simulation . 11-19 

11.6.5 DB, DM, and DW Display Comparison. 11-20 

11.6.6 Saving Simulator Status . 11-21 

11.7 Demonstration Program . 11-22 

11.8 Simulator Commands . 11-24 

A Common Object File Format A-1 

B Symbolic Debugging Directives B-1 

C Assembler Error Messages C-1 

D Linker Error Messages D-1 

E ASCII Character Set E-1 

F Glossary F-1 



























Illustrations 


Figure Page 

I- 1 TMS34010 Assembly Language Development Flow . 1-2 

3-1 Partitioning Memory into Logical Blocks . 3-3 

3-2 Using Sections Directives . 3-7 

3-3 Object Code Generated by Figure 3-2 . 3-8 

3-4 Default Allocation of the Object Code from Figure 3-2 3-10 

3-5 Combining Input Sections from Two Files (Default Allocation) . 3-11 

3-6 MEMORY and SECTIONS Directives for Figure 3-7 and Figure 3-8 3-12 

3-7 Memory Map Defined in Figure 3-6 3-13 

3-8 Placing the Code from Figure 3-4 into the Memory Map Defined by Figure 

3-6 . 3-14 

3- 9 An Example of Code that Generates Relocation Entries . 3-15 

4- 1 Assembler Development Flow . 4-2 

4-2 Sample Assembler Listing . 4-17 

4- 3 Cross-Reference Listing Format . 4-18 

5- 1 Sections Directives Example . 5-5 

5-2 Examples of Initialization Directives . 5-7 

5-3 An Example of the .space and .bes Directive . 5-7 

5-4 An Example of the .field Directive . 5-8 

5-5 An Example of the .even Directive . 5-9 

5-6 An Example of the .align Directive . 5-10 

5-7 Cache Segment Organization . 5-10 

5-8 An Example of Conditional Assembly .. 5-12 

5-9 An Example of the .even Directive . 5-24 

5-10 Examples of the .field Directive . 5-26 

5-11 An Example of the .usect Directive . 5-46 

7-1 An Example of a Macro Definition, Call, and Expansion . 7-5 

7-2 An Example of Using Parameter Values . 7-6 

7-3 An Example of a Conditional Block . 7-7 

7-4 An Example of a Repeatable Block . 7-8 

7- 5 An Example of Unique Labels . 7-9 

8- 1 Archiver Development Flow . 8-2 

9- 1 Linker Development Flow . 9-2 

9-2 An Example of a Linker Command File . 9-11 

9-3 An Example of a Command File with Linker Directives . 9-12 

9-4 An Example of the MEMORY Directive . 9-14 

9-5 Memory Map Defined in Figure 9-4 9-15 

9-6 An Example of the SECTIONS Directive . 9-16 

9-7 Section Allocation Defined by Figure 9-6 9-18 

9-8 The Most Common Method of Specifying Section Contents . 9-18 

9-9 An Example of Overlay Pages . 9-23 

9-10 Overlay Pages Defined by Figure 9-9 9-24 

9-11 SECTIONS Directive Definition for Figure 9-9 . 9-24 

9-12 ROM Model of Autoinitialization . 9-39 

9-13 RAM Model of Autoinitialization . 9-40 

9-14 Linker Command File, demo.cmd . 9-42 

9- 15 Output Map File, demo.map . 9-43 

10- 1 Object Format Converter Development Flow . 10-2 

II- 1 Simulator Development Flow . 11-2 

11- 2 Initial Simulator Display . 11-3 

vii 


















































11-3 Simulator Display Format . 11-5 

11-4 Simulator Help Menu . 11-10 

11 -5 Dedicated and Available TMS34010 Memory Spaces . 11-15 

11-6 DB, DM, and DW Displays . 11-20 

11-7 Display of Existing Breakpoints . 11-31 

11-8 Modify Breakpoints Menu . 11-33 

11 -9 Display Bytes Format . 11 -50 

11-10 Display Bytes Format - Over 10 Lines . 11-51 

11-11 Cache Contents Display . 11-53 

11-12 Memory Display . . 11 -54 

11 -1 3 A- and B-File Registers Display . 11-55 

11-14 I/O Registers Display . 11-56 

11-1 5 Display Word Format . 11-57 

11-16 Find Word Display . 11-61 

11-17 Graphics Customization Menu . 11-62 

11-18 Simulator Help Utility Menu . 11-66 

11-19 Interrupt Displays . 11-67 

11-20 Display Interrupt Options . 11-69 

11-21 I/O Registers Display . 11-73 

11-22 Graphics Environment Menu . 11-80 

11-23 Modify Memory Display . 11-82 

11-24 Modify Special Traps Display . 11-85 

11-25 gspinput.000 Example File . 11-11 

11-26 Display of Existing Traces . 11-11 

11-27 Trace Options Display . 11-12 

11-28 Trace on Address Display . 11-12 

11 -29 Trace on Address Pattern Display . 11-12 

11-30 Trace on Data Display . 11-12 

11-31 Trace on Pattern Display .. 11-12 

11-32 Trace on Range Display . 11-12 

11-33 Reverse-Assembly Display . 11-12 

11-34 Reverse-Assembly from a Starting Location Display . 11-12 

11 -35 Reverse-Assembly within a Range of Addresses Display . 11-12 

11-36 Evaluate Data Display . 11-13 

A-1 COFF File Structure . A-2 

A-2 Sample COFF Object File . A-3 

A-3 An Example of Section Header Pointers for the .text Section . A-7 

A-4 Line Number Blocks . A-10 

A-5 Line Number Entries Example . A-11 

A-6 Symbol Table Contents . A-12 

A-7 Symbols for Blocks . A-14 

A-8 Symbols for Functions . A-14 

A-9 Sample String Table . A-1 5 














































Tables 


Table Page 

4-1 Operators . 4-13 

4-2 Expressions with Absolute and Relocatable Symbols . 4-14 

4- 3 Symbol Attributes . 4-18 

5- 1 Directives Summary . 5-2 

6- 1 Summary of Arithmetic, Logical, and Compare Instructions . 6-23 

6-2 Summary of Move Instructions . 6-24 

6-3 Summary of Operand Formats for the MOVE Instruction . 6-25 

6-4 Summary of Operand Formats for the MOVB Instruction . 6-25 

6-5 Summary of Graphics Instructions . 6-26 

6-6 Summary of Operand Formats for the PIXT Instruction . 6-27 

6-7 Summary of Array Types for the PIXBLT Instruction . 6-27 

6-8 Immediate Operands Used by Graphics Instructions . 6-28 

6-9 Summary of Program Control and Context Switching Instructions . 6-29 

6-10 Summary of Jump Instructions . 6-30 

6-11 Condition Codes . 6-31 

6-12 Summary of Shift Instructions . 6-32 

6-13 Summary of XY Instructions . 6-33 

9-1 Linker Options Summary . 9-4 

9-2 Operators in Assignment Expressions . 9-32 

11-1 HIF ASCII Record Format . 11-18 

11-2 TI-PC Color Mapping . 11-19 

11-3 Addresses of Routines in the Demonstration Program . 11-23 

11-4 Simulator Command Summary . 11-24 

11-5 I/O Registers and Offsets . 11-74 

11-6 Pixel Processing Options . 11-92 

A-1 File Header Contents . A-4 

A-2 File Header Flags (Bytes 1 8 and 1 9) . A-4 

A-3 Optional File Header Contents . A-5 

A-4 Section Header Contents . A-6 

A-5 Section Header Flags (Bytes 36 and 37) . A-6 

A-6 Relocation Entry Contents . A-8 

A-7 Relocation Types (Bytes 8 and 9) . A-9 

A-8 Line Number Entry Format . A-10 

A-9 Symbol Table Entry Contents . A-13 

A-10 Special Symbols in the Symbol Tabie . A-1 3 

A-11 Symbol Storage Classes . A-16 

A-1 2 Special Symbols and Their Storage Classes . A-16 

A-13 Symbol Values and Storage Classes . A-17 

A-14 Section Numbers . A-18 

A-15 Basic Types . A-19 

A-16 Derived Types . A-19 

A-17 Auxiliary Symbol Table Entries Format . A-20 

A-18 Filename Format for Auxiliary Table Entries . A-20 

A-19 Section Format for Auxiliary Table Entries . A-21 

A-20 Tag Name Format for Auxiliary Table Entries . A-21 

A-21 End of Structure Format for Auxiliary Table Entries . A-21 

A-22 Function Format for Auxiliary Table Entries . .. A-22 

A-23 Array Format for Auxiliary Table Entries . A-22 

A-24 End of Blocks and Functions Format for Auxiliary Table Entries . A-22 


IX 




















































A-25 Beginning of Blocks and Functions Format for Auxiliary Table Entries . . . A-23 
A-26 Structure, Union, and Enumeration Names Format for Auxiliary Table Entries A-23 


x 



Section 1 


Introduction 


The TMS34010 Graphics System Processor (GSP) is an advanced 32-bit 
microprocessor optimized for graphics systems. The GSP is a member of the 
TMS340 family of computer graphics products from Texas Instruments. The 
TMS34010 is well supported by a full set of hardware and software develop¬ 
ment tools, including a C compiler, a full-speed emulator, a software simulator, 
and an IBM/TI-PC development board. This document discusses the software 
development tools that are included with the TMS34010 assembly language 
tools package: 

• Assembler 

• Archiver 

• Linker 

• Object format converter 

• Simulator 1 

These tools can be installed on the following systems: 

• PCs: 

- IBM-PC with PC-DOS 
-TI-PC with MS-DOS 

• VAX: 

-VMS 

- DEC Ultrix 

- Unix System V 

The TMS34010 assembly language tools create and use object files that are 
in common object file format, or COFF. COFF makes modular programming 
easier because it encourages you to think in terms of blocks of code and data. 
Object files contain separate blocks (called sections) of code and data that 
you can load into different memory spaces. You will be able to program the 
TMS34010 more efficiently if you have a basic understanding of COFF; Sec¬ 
tion 3, Introduction to Common Object File Format, discusses this object for¬ 
mat in detail. 

Topics covered in this introductory section include: 


Section Page 

1.1 Software Development Tools Overview .1-2 

1.2 Getting Started . 1 -4 

1.3 Manual Organization .1-5 

1.4 Related Documentation .1-6 

1.5 Style and Symbol Conventions.1 -7 


1 The simulator is available in a PC version only. 
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Introduction - Software Development Tools Overview 


1.1 Software Development Tools Overview 

Figure 1 -1 shows the TMS34010 assembly language development flow. The 
center section of the illustration highlights the most common path; the other 
portions are optional. 



Figure 1-1. TMS34010 Assembly Language Development Flow 
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Introduction - Software Development Tools Overview 


• The C compiler translates C source code into TMS34010 assembly 
language source code. The C compiler is not shipped as part of the as¬ 
sembly language tools package. 

• The assembler translates assembly language source files into machine 
language object files. Source files can contain TMS34010 assembly 
language instructions, assembler directives, and macro directives. You 
can use assembler directives to control various aspects of the assembly 
process, such as the source listing format, data alignment, and section 
content. 

• The archiver allows you to collect a group of files into a single archive 
file. For example, you can collect several macros together into a macro 
library. The assembler will search through the library and use the mem¬ 
bers that are called as macros by the source file. You can also use the 
archiver to collect a group of object files into an object library. The linker 
will include the members in the library that resolve external references 
during the link. 

• The linker combines object files into a single executable object module. 
As it creates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files 
(created by the assembler) as input. It can also accept archive library 
members and output modules created by a previous linker run. Linker 
directives allow you to combine object file sections, bind sections or 
symbols to specific addresses or within specific portions of memory, and 
define or redefine global symbols. 

• The main purpose of this development process is to produce a module 
that can be executed in a system that contains a TMS34010. You can 
use one of several debugging tools to refine and correct your code be¬ 
fore executing it in a TMS34010 system. These tools share similar de¬ 
bugger interfaces. (Note that only linked files can be executed.) 

- The simulator simulates TMS34010 functions in a configurable 
graphics environment. The simulator allows you to design, imple¬ 
ment, and evaluate both graphics and nongraphics software sys¬ 
tems. The simulator command set displays and maintains graphics 
and machine status information and controls execution of the 
software system under development. 

- The software development board (SDB) is a high- 
performance graphics card that can be used with a Tl or an IBM 
PC. The SDB is not shipped as part of the TMS34010 assembly 
language package. 

- The XDS/22 emulator is a realtime, in-circuit emulator. It is not 
shipped as part of the TMS34010 assembly language package. 

• Most EPROM programmers do not accept COFF object files as input. 
The object format converter converts a COFF object file into Intel 
hex, Tektronix hex, or Tl-tagged object format. The converted file can 
be downloaded to an EPROM programmer. 
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Introduction - Getting Started 


1.2 Getting Started 

The tools you will probably use most often are the assembler and the linker. 
This section provides a quick walkthrough so that you can get started without 
reading the whole user's guide. These examples show the most common 
methods for invoking the assembler and linker. 


1) First, create two short source files to use for the walkthrough; call them 

tiJLel.asm and fiie2.asm. 


filel .asm 

file2.asm 


. f ile 

"Set-Colors" 

. file 

"Set—Parms" 

COLORO 

. set 

B8 

EINT 



MOV I 

OFFFFh,COLORO 

CONTROL .set 

OCOOOOOBOh 

COLOR1 

. set 

B9 

MOVI 

4A4h,Al 


MOVI 

3333h,COLOR1 

MOVE 

Al,@CONTROL 




INTENB .set 

OCOOOOllOh 




MOVI 

OCOOh,A1 




MOVE 

Al,@INTENB 


2) Assemble filel.asm; enter: 
gspa filel 

The gspa command invokes the assembler. filel.asm is the input 
source file. (If the input file extension is .asm, you don't have to specify 
the extension; the assembler uses .asm as the default.) This example 
creates an object file called filel.obj. The assembler always creates 
an object file. You can specify a name for the object file, but if you don't, 
the assembler will use the input filename appended to the .obj extension. 

Now assemble file2.asm; enter: 

gspa file2 -1 

This time, the assembler creates an object file called file2.obj. The -I 
(lowercase "L") option tells the assembler to create a listing file; the list¬ 
ing file for this example is called f ile2.1st. 

3) Link filel.obj and file2.obj; enter: 
gsplnk filel file2 -o prog.out 

The gsplnk command invokes the linker, filel.obj and file2.obj 
are the input object files. (If the input file extension is .obj, you don't 
have to specify the extension; the linker uses .obj as the default.) The 
linker combines filel.obj and file2.obj to create an executable ob¬ 
ject module called prog.out (the -o option supplies the name of the 
output module). 

You can find more information about invoking the tools in the following sec¬ 
tions: 


Section Page 

4.1 Invoking the Assembler .4-3 

8.1 Archiver Development Flow ...8-2 

9.1 Invoking the Linker .9-3 

10.1 Invoking the Object Format Converter .10-3 

11.1 Invoking the Simulator.11-3 
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Introduction - Manual Organization 


1.3 Manual Organization 

Section 1 Introduction 

Provides an overview of the assembly language tools and the assembly lan¬ 
guage development process, gives quick examples for invoking the tools, lists 
related documentation, and explains the style and symbol conventions used 
throughout this document. 

Section 2 Software Installation 

Contains instructions for installing the assembly language tools on PC and 
VAX systems. 

Section 3 Introduction to Common Object File Format 

Discusses the basic COFF concept of sections and how they can help you 
use the assembler and linker more efficiently. (Common object file format, or 
COFF, is the object file format that the TMS34010 assembly language tools 
use.) Read Section 3 before using the assembler and linker. 

Section 4 Assembler Description 

Tells you how to invoke the assembler and discusses source statement format, 
valid constants and expressions, and assembler output. 

Section 5 Assembler Directives 

Divided into two parts: the first part describes the directives according to 
function, the second part is a reference that presents the directives in alpha¬ 
betical order. 

Section 6 Instruction Set Summary 

Summarizes the TMS34010 instruction set alphabetically. 

Section 7 Macro Language 

Describes macro directives and creating macros. 

Section 8 Archiver Description 

Contains instructions for invoking the archiver, creating new archive libraries, 
and modifying existing libraries. 

Section 9 Linker Description 

Tells you how to invoke the linker, provides details of linker operation, dis¬ 
cusses linker directives, and presents a detailed linking example. 

Section 10 Object Format Converter Description 

Tells you how to invoke the object format converter so that you can convert a 
COFF object file into an Intel or Tektronix hex object format. 

Section 11 Simulator Description 

Contains instructions for invoking the simulator and loading the tutorial pro¬ 
gram, explains the various fields on the simulator screen, and contains a 
complete alphabetical reference of simulator commands. 

Appendix A Common Object File Format 

Contains specific information about the internal format of COFF object files. 

Appendix B Symbolic Debugging Directives 
Appendix C Assembler Error Messages 
Appendix D Linker Error Messages 
Appendix E ASCII Character Set 
Appendix F Glossary 
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Introduction - Related Documentation 


1.4 Related Documentation 

The following TMS34010 documents are also available. 

• The TMS34010 User's Guide (literature number SPVU001) discusses 
hardware aspects of the TMS3401 0, such as pin functions, architecture, 
stack operation, and interfaces, and contains the TMS34010 instruction 
set. (If you received this User's Guide with the TMS34010 assembly 
language tools package, you should also have received a copy of the 
/ MS34010 User's Guide). 

• The TMS34010 Data Sheet (literature number SPVS002) contains the 
recommended operating conditions, electrical specifications, and timing 
characteristics of the TMS34010. 

• The TMS34010 C Compiler User's Guide (literature number 
SPVU005) tells you how to use the TMS34010 C compiler. This C 
compiler accepts standard Kernighan and Ritchie C source code and 
produces TMS34010 assembly language source code. We suggest that 
you use The C Programming Language (written by Brian W. Kernighan 
and Dennis M. Ritchie, published by Prentice-Hall) as a companion to 
the TMS34010 C Compiler User's Guide. 

• The TMS34010 Software Development Board User's Guide (lit¬ 
erature number SPVU002) describes using the TMS34010 software de¬ 
velopment board (a high-performance, PC-based graphics card) for 
testing and developing TMS34010-based graphics systems. 

• The TMS34010 Software Development Board Schematics (liter¬ 
ature number SPVU003) is a companion to the TMS34010 Software 
Development Board User's Guide. 

• The TMS34010 Font Library User's Guide (literature number 
SPVU007) describes a set of fonts that are available for use in a 
TMS34010-based graphics system. 
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1.5 Style and Symbol Conventions 

• In this document, program listings, program examples, interactive displays, file¬ 
names, and symbol names are shown in a special font. Examples use a bold 
version of the special f ont for emphasis. Here is a sample program listing: 


0011 

00000210 

0001 

.field 

1, 

2 

0012 

00000212 

0003 

.field 

3, 

4 

0013 

00000215 

0006 

.field 

6, 

3 

0014 

00000220 


. even 




• In syntax descriptions, the instruction, command, or directive is in a bold face 
font and parameters are in italics. Portions of a syntax that are in bold face 
should be entered as shown; portions of a syntax that are in italics describe the 
type of information that should be entered. Here is an example of an instruction 
syntax: 

CVXYL Rs, Rd 

CVXYL is the instruction. This instructions has two parameters, indicated by Rs 
and Rd Rs and Rd are abbreviations for source register and destination register, 
when you use CVXYL, these parameters must be real register names (such as AO, 
B1, etc.). 

• Square brackets ( [ and ] ) indicate an optional parameter. Here's an example of 
a directive that has an optional parameter: 

.field value [, size in bits] 

The .field directive has two parameters. The first parameter, value, is required. 
The second parameter, size in bits , is optional. As this syntax shows, if you use 
the optional second parameter, you must precede it with a comma. 

Square brackets are also used as part of the pathname specification for VMS 
pathnames; in this case, the brackets are actually part of the pathname (they aren't 
optional). 

• Some parameters must be enclosed in double quotes. For example, consider the 
.sect directive: 

.sect "section name" 

This directive has one parameter, section name. When you use .sect, this parameter 
must be an actual section name, and it must be enclosed in double quotes. 

• Braces ( { and } ) indicate a list. The | symbol (read as or) separates items within 
a list. Here's the syntax of a simulator command that shows an example of a list: 

MM address { 16-bit-value | 32-bit-value | assembler-statement } 

The MM command has two parameters. The first parameter must be an address ; 
the second parameter can be a 16-bit value, a 32-bit value, or an assembler 
statement. 

• Some directives can have a varying number of parameters. For example, the .byte 
directive can have up to 100 parameters. The syntax for this directive is: 

.byte valuei [ r ..., value n ] 

This syntax shows that .byte must have at least one value parameter, but you have 
the option of supplying additional value parameters, separated by commas. 
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Section 2 


Software Installation 


This section contains step-by-step instructions for installing and executing the 
assembler, archiver, linker, object format converter, and simulator 2 3 . This soft¬ 
ware can be installed on four operating systems: 

IBM and TI PCs 

• PC-D0S3 (IBM PC) 

• MS-DOS 4 (Tl PC) 

Digital Equipment Corporation VAX-11 5 

• VMS operating system 

• DEC Ultrix operating system 

• Unix System V operating system 

You will find installation instructions for these systems in the following sec¬ 
tions: 


Section Page 

2.1 PC Installations . 2-2 

2.2 VAX/VMS Installation .2-4 

2.3 VAX/ULTRIX and System V Installation .2-4 


Section 1.5 (page 1 -7) describes style and symbol conventions that are used 
in this section. 


2 The simulator is available in a PC version only. 

3 PC-DOS is a trademark of International Business Machines. 

4 MS is a trademark of Microsoft Corporation. 

5 VAX-11 and VMS are trademarks of Digital Equipment Corporation. 
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2.1 Installation for IBM/TI PCs with PC/MS-DOS 

The TMS34010 software package is shipped on several double-sided, dou¬ 
ble-density diskettes. Note that two versions of the simulator are shipped 
(one is for the IBM-PC and one is for the TI-PC). Use the simulator that Is 
appropriate for your system; refer to the release notes for more information. 

The tools execute in batch mode on PC-DOS (IBM PC) and MS-DOS (Tl PC) 
systems. At least 51 2K bytes of memory space must be available in your sys¬ 
tem. 

These instructions are for both hard-disk, single-drive, and and dual-drive 
systems. On a dual-drive system, the MS/PC-DOS system diskette should 
be in drive B. The instructions use these symbols for drive names: 

A: Floppy disk drive for hard-disk and single-drive systems or source drive 

for dual-drive systems. 

B: Destination or system disk drive for dual-drive systems. 

C: Winchester (hard disk) for hard disk systems. (E: on Tl PCs.) 

1) Make backups of the product diskettes. First format a blank diskette. 
Insert a blank (destination) diskette in drive A. Enter: 

FORMAT A: CR 

When MS/PC-DOS prompts: format another (y/n)?, respond with 
N. Now copy the disks. 

• On hard-disk or single-drive systems, enter: 

DISKCOPY A: A: CR 

Follow the system prompts, removing and inserting the product 
and blank diskettes as directed. When MS/PC-DOS prompts: 

copy another ( y/n) ?, respond with N. 

• On dual-drive systems, place a product diskette in drive A: and a 
blank, formatted diskette in drive B. Enter: 

COPY A:*.* B :*.* CR 

2) Create a directory to contain the TMS34010 software. 

• On hard-disk or single-drive systems, enter: 

MD E:\GSPTOOLS CR 

• On dual-drive systems, enter: 

MD B:\GSPTOOLS CR 
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3) Copy the TMS34010 tools onto the hard disk or the system disk. (Re¬ 
member, you have two copies of the simulator disk - copy only one.) 

• On hard disk or single-drive systems, enter: 

COPY A:\*.* E:\GSPTOOLS\*.* CR 

• On dual-drive systems, enter: 

COPY A:\*.* B:\GSPTOOLS\*.* CR 
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2.2 Installation for VAX/VMS 

The TMS34010 software tape was created with the VMS BACKUP utility at 
1600 BPI. These tools were developed on version 4.4 of VMS. If you are 
using an earlier version of VMS, you must relink the object files; refer to the 
release notes for relinking instructions. 

1) Mount the tape on your tape drive. 

2) Execute the following commands. Note that you must create a destina¬ 
tion directory for the tools; in this example, DEST: directory represents 
that directory. Replace tape: with the name of the tape drive you are 
using. 

$ allocate TAPE: 

$ mount/for/den=1600 TAPE: 

$ backup TAPE:GSP.bck DEST:directory 

$ dismount TAPE: 

$ dealloc TAPE: 

3) The product tape contains a file called setup.com. This file sets up 
VMS symbols that allow you to execute the tools in the same manner 
as other VMS commands. Execute the file as follows: 

$ @setup DEST:directory 

This sets up symbols that you can use to call the various tools. As the 
file is executed, it will display the defined symbols on the screen. 


2.3 Installation for VAX/ULTRIX and VAX/System V 

This tape was made at 1600 BPI using the TAR utility. Follow these in¬ 
structions to install the software: 

1) Mount the tape on your tape drive. 

2) Make sure that the directory that you'll store the tools in is the current 
directory. 

3) Enter the TAR command for your system; for example, 
tar x 

This copies the entire tape into the directory. 
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Section 3 


Introduction to Common Object File Format 


The assembler and linker create object files that are in a format called common 
object file format, or COFF 

COFF makes modular programming easier because it encourages you to think 
in terms of blocks of code and data when you write an assembly language 
program. These blocks are known as sections. Both the assembler and the 
linker provide directives that allow you to create and manipulate sections. 

This chapter provides an overview of COFF sections and includes the follow¬ 
ing topics: 


Section Page 

3.1 Sections .3-2 

3.2 How the Assembler Handles Sections .3-3 

3.3 How the Linker Handles Sections .3-9 

3.4 Relocation .3-15 

3.5 Loading a Program .3-16 

3.6 Symbols in a COFF File . 3-17 


Appendix A details COFF object file structure; for example, it describes the 
fields in a file header and the structure of a symbol table entry. Appendix A 
is mainly useful for those of you who are interested in the internal format of 
object files. 
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3.1 Sections 

The smallest relocatable unit of an object file is called a section. A section 
is a relocatable block of code or data which will (ultimately) occupy contig¬ 
uous space in the TMS34010 memory map. Each section of an object file is 
separate and distinct from the other sections. COFF object files always con¬ 
tain three default sections: 

• The .text section usually contains executable code. 

• The .data section usually contains initialized data. 

• The .bss section usually reserves space for uninitialized variables. 

In addition, the assembler and linker allow you to create, name, and link 
named sections that are used similarly to the .data, .text, and .bss sections. 

It is important to note that there are two basic types of sections: 

• Initialized sections contain data or code. The .text and .data sections 
are initialized; named sections created with the .sect assembler directive 
are also initialized. 

• Uninitialized sections reserve space in the memory map for uninitial¬ 
ized data. The .bss section is uninitialized; named sections created with 
the .usect assembler directive are also uninitialized. 

The assembler provides several directives that allow you to associate various 
portions of code and data with the appropriate sections. The assembler builds 
these sections during the assembly process, creating an object file that is or¬ 
ganized similarly to the object file shown in Figure 3-1. 

One of the linker's functions is to relocate sections into the target memory map 
(this is called allocation). Since most systems contain several different types 
of memory, using sections can help you to use target memory more efficiently. 
All sections are independently relocatable; you can place different sections 
into various blocks of target memory. For example, you can define a section 
that contains an initialization routine, and then allocate the routine into a 
portion of the memory map that contains EPROM. 

Figure 3-1 shows the relationship between sections in an object file and a 
hypothetical target memory. 
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Object File 


Target Memory 



0 


3 X 2? 6 


Figure 3-1. Partitioning Memory into Logical Blocks 


3.2 How the Assembler Handles Sections 

The assembler's main function in regard to sections is to identify the portions 
of an assembly language program that belong in a particular section. The as¬ 
sembler has six directives that support this function: 

• The .bss and .usect directives reserve defined amounts of space in 
memory (usually RAM). This reserved space is used for storing vari¬ 
ables. 

• The .text directive identifies the source statements that follow it as 
executable code. The statements following a .text directive are assem¬ 
bled into the .text section. 

• The .data directive identifies the source statements that follow it as 
initializable data. The statements following a .data directive are assem¬ 
bled into the .data section. 

• The .sect directive defines named sections that are used like the .text 
and .data sections. The statements following a .sect directive are as¬ 
sembled into the named section. 

The .bss and .usect directives create uninitialized sections) the .text, .data, and 
.sect directives create initialized sections. 


Note: 

If you don't use any of the sections directives, the assembler assembles 
everything into the .text section. 
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3.2.1 Uninitialized Sections 

Uninitialized sections reserve space in memory; they are usually allocated into 
RAM. These sections have no actual contents in the object file; they simply 
reserve memory. A program can use this space at run time for creating and 
storing variables. 

Uninitialized data areas are built by using the .bss and .usect assembler direc¬ 
tives. The .bss directive reserves space m the .bss section. The .usect directive 
reserves space in a specific uninitialized named section. Each time you invoke 
the .bss directive, the assembler reserves more space in the .bss section. Each 
time you invoke the .usect directive, the assembler reserves more space in the 
specified named section. 

The syntaxes for these directives are: 

.bss symbol, size in bits 

symbol .usect "section name", size in bits 

• The symbol points to the first bit reserved by this invocation of the .bss 
or .usect directive. The symbol corresponds to the name of the variable 
that you're reserving space for. It can be referenced by any other section 
and can also be declared as a global symbol (with the .global assembler 
directive). 

• The size is an absolute expression. The .bss directive reserves size bits 
in the .bss section; the .usect directive reserves size bits in section 
name. 

• The section name parameter tells the assembler which named section to 
reserve space in. (For more information about named sections, see 
Section 3.2.3.) 

The .text, .data, and .sect directives tell the assembler to stop assembling into 
the current section and begin assembling into the indicated section. The .bss 
and .usect directives, however, do not end the current section and begin a 
new one; they simply "escape" from the current section temporarily. The .bss 
and .usect directives can appear anywhere in an initialized section without 
affecting the contents of the initialized section. 

3.2.2 Initialized Sections 

Initialized sections contain executable code or initialized data. The contents 
of these sections are stored in the object file and placed in memory when the 
program is loaded. Each initialized section is separately relocatable and may 
reference symbols that are defined in other sections. The linker automatically 
resolves these section-relative references. 

Three directives tell the assembler to place code or data into a section. The 
syntaxes for these directives are: 

.text 

.data 

.sect "section name" 
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When the assembler encounters one of these directives, it stops assembling 
into the current section (acting as an implied "end current section" command). 
It then assembles subsequent code into the respective section until it en¬ 
counters another .text, .data, or .sect directive. 

Sections are built up through an iterative process. For example, when the 
assembler first encounters a .data directive, the .data section is empty. The 
statements following this first .data directive are assembled into the .data 
section (until the assembler encounters a .text or .sect directive). If the as¬ 
sembler encounters subsequent .data directives, it adds the statements fol¬ 
lowing these .data directives to the statements that are already in the .data 
section. This creates a single .data section that can be allocated contiguously 
into memory. 

3.2.3 Named Sections 

Named sections are sections that you create. You can use them like the de¬ 
fault .text, .data, and .bss sections, but they are assembled separately from the 
default sections. 

For example, repeated use of the .text directive builds up a single .text section 
in the object file. When linked, this .text section is allocated into memory as 
a single unit. Suppose there is a portion of executable code (perhaps an in¬ 
itialization routine) that you don't want allocated with .text. If you assemble 
this segment of code into a named section, it will be assembled separately 
from .text, and you will be able to allocate it into memory separately from .text. 
(Note that you can also assemble initialized data that is separate from the .data 
section, and you can reserve space for variables that is separate from the .bss 
section.) 

Two directives let you create named sections: 

• The .usect directive creates sections that are used like the .bss section. 
These sections reserve space in RAM for variables. 

• The .sect directive create sections that are used like the default .text and 
.data sections. 

The syntaxes for these directives are: 
symbol .usect "section name" r size 
.sect "section name" 

The section name parameter is the name of the section. Section names are 
significant to 8 characters. You can create up to 32,767 separate named sec¬ 
tions. 

Each time you invoke one of these directives with a new name, you create a 
new named section. Each time you invoke one of these directives with a name 
that is already used, the assembler assembles the additional code or data (or 
reserves space) into the section with that name. You cannot use the same 
names with different directives. That is, you cannot create a section with the 
.usect directive and then try to use the same section with .sect. 
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3.2.4 Section Program Counters 

The assembler maintains a separate program counter for each section. These 
program counters are known as section program counters , or SPCs. 

An SPC represents the current address within a section of code or data. Ini¬ 
tially, the assembler sets each SPC to 0. As the assembler fills a section with 
code or data, it increments the appropriate SPC. If you resume assembling 
into a section, the assembler remembers the appropriate SPC's previous value 
and continues incrementing the SPC at that point. 

The assembler treats each section as if it begins at address 0; the linker relo¬ 
cates each section according to its final location in the memory map. 

3.2.5 An Example That Uses Sections Directives 

Figure 3-2 shows how you can build COFF sections incrementally, using the 
sections directives to swap back and forth between the different sections. You 
can use sections directives: 

• To begin assembling into a section for the first time, or 

• To continue assembling into a section that already contains code. In this 
case, the assembler simply appends the new code to the code that is 
already in the section. 

The format of this example is a listing file. By using a listing file, this example 
shows how the SPCs are modified during assembly. A line in a listing file has 
four fields: 

1) The first field contains the source code line counter. 

2) The second field contains the section program counter. 

3) The third field contains the object code. 

4) The fourth field contains the original source statement. 
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** Assemble an initialized table into .data ** 


00000000 .data 

00000000 00000040 pixvals: .long 
00000020 00000020 
00000040 00000010 

0005 pbuf_sz: .set 


; (produces no object code) 


00000000 

00000020 


00000060 

00000080 

000000A0 


11111111 

22222222 

33333333 


** Reserve space in .bss for two variables ** 

.bss varl, 32, 1 

.bss pix_buf, pbuf—sz * 16, 1 

** Still in .data ** 


colors: .long 


****************************** 
Ollllllllh, 022222222h, 033333333h 


** Assemble code into the .text section ** 
************************************************ 


0021 

00000000 


. text 



0022 

00000000 

09E0 init_a: 

MOV I 

pix—buf, 

A0 


00000010 

00000020+ 




0023 

00000030 

07A2 

MOVE 

@colors, 

A2,l 


00000040 

00000060" 




0024 

00000060 

2602 

SLL 

16, A2 


0025 

00000070 

05A3 

MOVE 

@pixvals, 

, A3 


00000080 

00000000" 



0026 

000000A0 

EE43 

MOVY 

A2, A3 


0027 

000000B0 

09C4 

MOVI 

pbuf—sz, 

A4 


ooooooco 

0005 




00000000 

00000000 

00000020 

00000040 


00000000 

00000010 


00000006 

00000005 

00000004 


************************************************ 
** Assemble another initialized table into ** 
** a named section called powers ** 

************************************************ 

.sect "powers" 

powers: .long 6, 5, 4 


************************************************ 
** Define an uninitialized named section to ** 
** reserve more space for variables ** 

************************************************ 

var2: .usect "newvars", 1 * 16, 1 

inbuf: .usect "newvars", 8 * 16, 1 


000000D0 

000000D0 

000000E0 


9260 aloop: 
3C44 


************************************************ 

** Assemble more code into .text ** 

************************************************ 

. text 

aloop: MOVE A3, *A0+, 1 

DSJS A4, aloop 


Figure 3-2. Using Sections Directives 
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As Figure 3-3 shows, the file in Figure 3-2 creates five sections: 

.text contains 240 bits of object code. 

.data contains 192 bits of object code. 

.bss reserves 112 bits in memory. 

powers is a named section created with the .sect directive; it contains 96 
bits ot initialized data. 

newvars is a named section created with the .usect directive; it reserves 144 
bits in memory. 

In Figure 3-3, note that the first column shows the source statements in Figure 
3-2 that generate the object code in column 2. 


Line Numbers Object Code Section 


22 

O9E0 

22 

00000020+ 

23 

07A2 

23 

00000060" 

24 

2602 

25 

05 A3 

25 

00000000" 

26 

EE43 

27 

0904 

27 

0005 

45 

9260 

46 

3C44 

5 

00000040 

5 

00000020 

5 

OOQOO01.0 

17 

11111111 

17 

22222222 

17 

33333333 


.text 


.data 


NO .bss 

ii, 12 mrnrnmm 

reserved 


33 amooom powers 

33 00 mms (initialized 

33 ••OOQOOOQ4.. , j named section) 


38, 39 


No data- 
144 bits 
reserved 


newvars 
(uninitialized 
named section) 


Figure 3-3. Object Code Generated by Figure 3-2 
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3.3 How the Linker Handles Sections 

The linker has two main functions in regard to sections. First, the linker uses 
the sections in COFF object files as building blocks; it combines input sections 
(when more than one file is being linked) to create output sections in an ex¬ 
ecutable COFF output module. Second, the linker chooses memory addresses 
for the output sections. 

The linker provides two directives that support these functions: 

• The MEMORY directive allows you to define the memory map of a tar¬ 
get system. You can name portions of memory and specify their starting 
addresses and their lengths. 

• The SECTIONS directive tells the linker how to combine input sections 
and where to place the output sections in memory. 

It is not always necessary to use linker directives. If you don't use them, the 
linker uses the default allocation algorithm described in Section 3.3.1. When 
you do use linker directives, you must specify them in a linker command file. 

Refer to the following sections for more information about linker command 
files and linker directives: 


Section Page 

9.4 Linker Command Files .9-11 

9.6 The MEMORY Directive .9-14 

9.7 The SECTIONS Directive .9-16 


3.3.1 Default Allocation 

You can link files without specifying a MEMORY or SECTIONS directive. The 
linker uses a default model to combine sections (if necessary) and allocate 
them into memory. When using the default model, the linker: 

1) Assumes that memory begins at address 0, and assumes that 3 x 2 26 
words are available to allocate object code into. 

2) Allocates .text into memory beginning at address 0. 

3) Allocates .data into memory immediately following .text. 

4) Allocates .bss into memory, immediately following .data. 

5) Allocates any named sections, immediately following .bss. Named sec¬ 
tions are allocated in the order that the linker encounters them in the 
input files. 

Figure 3-4 shows how a single file would be allocated into memory using 
default allocation. Note that the linker does not actually place object code into 
memory; it assigns addresses to sections to that a loader can place the code 
into memory. 


3-9 







Introduction to COFF - How the Linker Handies Sections 


Object Code 


Q9EG 

00000020 

07A2 

00000060 

2602 

05A3 

00000000 

EE43 

09C4 

0005 

9260 

3C44 


mmmmrn 
00000020 
00000010 
: 1111 in t 
22222222 
33333333 


m 

irigSeiiiei;:: 


00000006 

0000Q005 

00000004 


No data- 
144 bits 
reserved 


Memory 


n>: 

t! 

3>::: 


.text 


.data 


\bas 


powers 


unused 


OOOOOOOOh 


OOOOOOEOh 

OOOOOOFOh 


00000lAOh 
OOOOOIBOh 


0000021 Oh 
00000220h 


00000270h 

00000280h 


00000300h 
0000031Oh 


OFFFFFFOh 


Figure 3-4. Default Allocation of the Object Code from Figure 3-2 


As Figure 3-4 shows, the linker: 

1) Allocates the .text section, beginning at address 0. The .text section 
contains 240 bits of object code. 

2) Allocates the .data section next, beginning at address 180h. The .data 
section contains 192 bits of data. 

3) Allocates the .bss section, beginning at address 380h. The .bss section 
reserves 112 bits in memory. 

4) Allocates the initialized named section powers at address 390h. The 
powers section contains 96 bits of data. 

5) Allocates the uninitialized named section newvars at address 4F0h. The 
newvars section reserves 144 bits in memory. 

Note that the space between addresses 0300h-0FFFFFFF0h is not used. 
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Figure 3-5 shows a simple example of how two files would be linked together. 
When you link several files using the default algorithm, the linker combines 
all input sections that have the same name into one output section that has 
this same name. For example, the linker combines the .text sections from two 
input files to create one .text output section. 


filel.obj Memory 



Figure 3-5. Combining Input Sections from Two Files (Default 

Allocation) 


In Figure 3-5, filel.obj and file2.obj each contain the .text, .data, and 
.bss default sections, an initialized named section called Table_l, and an 
uninitialized named section called U-vars. file2.obj also contains an in¬ 
itialized named section called Constants. As Figure 3-5 shows, the linker: 

1) Combines f ilel .text with f ile2 .text to form one .text output section. 
The .text output section is allocated at address 0. 

2) Combines filel .data with file2 .data to form the .data output sec¬ 
tion. The .data output section is allocated following the .text output 
section. 

3) Combines filel .bss with file2 .bss to form the .bss output section. 
The .bss output section follows the .data section in memory. 
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4) Combines filel Table_l with f ile2 Table_l to form the Table_l 
output section. (The Table-1 section is the first named section that the 
linker encounters, so it is allocated before the other named sections.) 
The Table—1 output section is allocated following the .bss output sec¬ 
tion. 

5) Combines filel U-vars with file2 U_vars to form the U_vars 
output section. The U-vars output section is allocated following the 
.bss output section. 

6) Allocates the Constants section from f ile2 after the U-vars section. 


Note: 

The maximum size of an output section is OFFFFFFFh bits. 


3.3.2 Placing Sections in the Memory Map 

Figure 3-4 and Figure 3-5 illustrate the linker's default methods for combining 
sections and allocating them into memory. Sometimes you may not want to 
use the default setup. For example, you may not want to combine all of the 
.data sections into a single .data output section. Or, you might want to place 
a named section at address 0 instead of the .text section. Most memory maps 
are comprised of various types of memories (DRAM, VRAM, EPROM, etc.) in 
varying amounts; you may want to place a section in a particular type of me¬ 
mory. 

The next three illustrations show another possible combination of the sections 
from Figure 3-4. Figure 3-6 contain MEMORY and SECTIONS definitions 
that define a memory map and allocate the sections from Figure 3-4 into the 
defined memory. Figure 3-7 shows how the ranges defined in Figure 3-6 fit 
into the memory map. Figure 3-8 shows how the sections from Figure 3-4 
are allocated into the memory map. 


MEMORY 

{ 

display 

code 

space 


origin 

origin 

origin 


Oh 

ODOOOOOOOh 

OFFEOOOOOh 


length = OlFFFFOh 
length = 03FFFF0h 
length = OlFFFFOh 


SECTIONS 

{ 


.text ODOOOOOOOh 

{ 

} 



powers ALIGN(32) 

{ 

} 

> 

code 

. data 

{ 

} 

> 

code 

newvars 

{ 

} 

> 

space 

.bss 

{ 

} 

> 

space 


Figure 3-6. MEMORY and SECTIONS Directives for Figure 3-7 and 

Figure 3-8 
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In Figure 3-6, 

• The MEMORY directive defines three memory ranges: display, code, 
and space. 

The origin for each of these ranges identifies the memory range's starting 
address in memory. The length specifies the length of the range. 

For example, memory range space has a starting address OFFEOOOOOh 
and a length of 01 FFFOh; it defines the addresses OFFEOOOOOh through 
OFFFFFFFOh in memory. 

Note that this MEMORY definition does not define the addresses be¬ 
tween 01 FFFFOh and OCFFFFFFFh. This range is unconfigured. As 
far as the linker is concerned, this area does not exist, and no code or 
data can be loaded into it. Whenever you use the MEMORY directive, 
only the memory ranges that the directive defines can contain code or 
data. 

• The SECTIONS directive defines the order in which the sections are al¬ 
located into memory. The .text section must begin at address 
ODOOOOOOOh. The powers section is allocated into the named memory 
range code Since code starts at ODOOOOOOOh and .text starts at address 
ODOOOOOOOh, powers will follow .text; it must be aligned on the next 
available address that is a multiple of 32 bits. The .data section is allo¬ 
cated into memory range code following powers. The newvars section 
is allocated into the first available address in the named memory range 
space; the .bss section follows newvars. 

Figure 3-7 shows how the ranges defined by the MEMORY directive in Figure 

3-6 fit into the memory map. 



OOOOOOOOOh 


OOOIFFFEFh 
0001FFFFOh 


OCFFFFFFFh 

ODOOOOOOOh 


0D03FFFEFh 

0D03FFFF0h 


OFFDFFFFFh 

OFFEOOOOOh 


OFFFFFFEFh 

OFFFFFFFOh 


Figure 3-7. Memory Map Defined in Figure 3-6 
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Introduction to COFF - How the Linker Handles Sections 


Figure 3-8 shows how the sections from Figure 3-4 are allocated into the 
memory ranges defined in Figure 3-6. Note that some of the memory is con¬ 
figured but unused. For example, the newvars and .bss sections are allocated 
into the space area. The length of the space range is 01 FFFFOh words; 
however, the combined lengths of the newvars and .bss sections is only IQOh 
words. Thus, locations 0FFE001 OOh-OFFFFFFFOh are unused. 


... OOOIFFFEFh 

yTZmZffi, OOOIFFFFOh 
/unconfigured/ 


unused 


.text 


unused 


;>:pbwers::; 


Xv unused *Xv 



newvars 


■Xv unused *Xv 


OOOOOOOOOh 


OCFFFFFFFh 

ODOOOOOOOh 

ODOOOOOOEh 

ODOOOOOOFh 

ODOOOOOlOh 

0D0000015h 

0D0000016h 


0D0000021h 

0D0000022h 


0D03FFFEFh 

0D03FFFF0h 


OFFDFFFFFh 

OFFEOOOOOh 


0FFE00008h 

0FFE00009h 


OFFEOOOOFh 

OFFEOOOlOh 


OFFFFFFFFh 


Figure 3-8. Placing the Code from Figure 3-4 into the Memory Map 
Defined by Figure 3-6 
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Introduction to COFF - Relocation 


3.4 Relocation 

The assembler treats each section as if it begins at address 0. All relocatable 
symbols (labels) are relative to address 0 in their sections. Of course, all sec¬ 
tions can't actually begin at address 0 in memory, so the linker relocates 
sections by: 

• Allocating sections into the memory map so that they begin at the ap¬ 
propriate address, 

• Adjusting symbol values to correspond to the new section addresses, 

and 

• Adjusting references to relocated symbols to reflect the adjusted symbol 
values. 

The linker uses relocation entries to adjust references to symbol values. The 
assembler creates a relocation entry each time a relocatable symbol is refer¬ 
enced. The linker then uses these entries to "patch" the references after the 
symbols are relocated. Figure 3-9 contains a code segment that generates 
relocation entries. 


0001 



. ref 

X 




0002 

00000000 


. text 





0003 

00000000 

C080 

JAUC 

X 

Creates 

a reloc. 

entry 


00000010 

00000000! 





0004 

00000020 

0300 Y: 

NOP 





0005 

00000030 

05A0 

MOVE 

@Y, A0 ; 

; Creates 

a reloc. 

entry 


00000040 

00000020’ 





Figure 3-9. An Example of Code that Generates Relocation Entries 


In Figure 3-9, both symbols x and Y are relocatable. x is defined in some 
other module; Y is defined in the .text section of this module. When assem¬ 
bled, x has a value of 0 (the assembler assumes all undefined external symbols 
have values of 0) and Y has a value of 20h (relative to address 0 in the .text 
section). The assembler generates two relocation entries, one for x and one 
for Y. The reference to x is an external reference (indicated by the ! character 
in the listing). The reference to Y is to a relocatable symbol defined internally 
in the .text section (indicated by the ' character in the listing). After linking, 
suppose that x is relocated to address lOOh. Suppose also that the .text sec¬ 
tion is relocated to begin at address 2000h; Y now has a relocated value of 
2020h. The linker uses the two relocation entries to patch the two references 
in the object code: 


C080 JAUC X 
00000000 


becomes C080 

00000100 


05A0 MOVE @Y, A0 becomes 

00000020 


05A0 

00002020 


Each section in a COFF object file has a table of relocation entries. The table 
contains one relocation entry for each relocatable reference in the section. The 
linker usually removes relocation entries after it uses them. This prevents the 
output file from being relocated again (if it is relinked or when it is loaded). 
A file that contains no relocation entries is an absolute file (all its addresses 
are absolute addresses). If you want the linker to retain relocation entries, 
invoke the linker with the -r option. 
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Introduction to COFF - Loading a Program 


3.5 Loading a Program 

The linker produces executable COFF object modules. An executable object 
file has the same COFF format as object files that are used as linker input; 
however, the sections in an executable object file are combined and relocated 
to fit into target memory. 

In order to run a program, the data in the executable object module must be 
transferred, or loaded, into target system memory. 

Several methods can be used for loading a program, depending on the exe¬ 
cution environment. Some of the more common situations are listed below. 

• Several of the TMS34010 debugging tools (such as the XDS emulator) 
have built-in loaders. Each of these tools has a LOAD command that 
invokes a COFF loader; the loader reads the executable file and copies 
the program into target memory. 

• The TMS34010 software development board includes a stand-alone 
loader that allows you to load code into a target system, begin program 
execution, and then return to the operating system. The source for this 
loader is included with the SDB. 

• If you are using a ROM- or EPROM-based system, you can use the ob¬ 
ject format converter (which is shipped as part of the assembly language 
package) to convert the executable COFF object module into one of 
several ASCII object file formats. You can then use the converted ASCII 
file with an EPROM programmer to burn the program into an EPROM. 

• Some TMS34010 programs are loaded under the control of an operating 
system or monitor software running directly on the target system. In this 
type of application, the target system usually has an interface to the file 
system on which the executable module is stored. You must write a 
custom loader for this type of system. The loader must comprehend the 
file system (in order to access the file) as well as the memory organiza¬ 
tion of the target system (to load the program into memory). 
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3.6 Symbols in a COFF File 

A COFF file contains a symbol table that stores information about symbols in 
the program. The linker uses this table when it performs relocation. Debug¬ 
ging tools can also use the symbol table to provide symbolic debugging. 


3.6.1 External Symbols 

External symbols are symbols that are defined in one module and referenced 
in another module. You can use the .global directive to identify symbols as 
external. In a source module, an external symbol can be either: 


• Defined in the current module and used in another module, or 

• Defined in another module and referenced in the current module. 


The following code segment illustrates these definitions. 


x: .set 056h 

MOVE @y, A1 

.global x 
.global y 


Define x 
Reference y 
DEF of x 
REF of y 


The .global definition of x says that it is an external symbol defined in this 
module, and that other modules can reference x. The .global definition of y 
says that it is an undefined symbol that is defined in some other module. 


The assembler places both x and y in the object file's symbol table. When the 
file is linked with other object files, the entry for x defines unresolved refer¬ 
ences to x from other files. The entry for y causes the linker to look through 
the symbol tables of other files for y's definition. 


The linker must match all references with corresponding definitions. If the 
linker cannot find a symbol's definition, it prints an error message about the 
unresolved reference. This type of error prevents the linker from creating an 
executable object module. 


3.6.2 The Symbol Table 

The assembler always generates an entry in the symbol table when it en¬ 
counters an external symbol (both definitions and references). The assembler 
also creates special symbols that point to the beginning of each section; the 
linker uses these symbols to relocate references to other symbols in a section. 

The assembler does not usually create symbol table entries for any other type 
of symbol because the linker does not use them. For example, labels are not 
included in the symbol table unless they are declared with .global. For sym¬ 
bolic debugging purposes, it is sometimes useful to have entries in the symbol 
table for each symbol in a program. To accomplish this, invoke the assembler 
with the -s option. 
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Section 4 


Assembler Description 


The assembler translates assembly language source files into machine language 
object files. These files are in common object file format (COFF), discussed in 
Section 3. Source files can contain these assembly language elements: 

• Assembler directives (described in Section 5), 

• Assembly language instructions (summarized in Section 6), and 

• Macro directives (described in Section 7). 

The assembler: 

• Is a two-pass assembler, with an intermediate pass for optimizing jump 
instructions. 

• Processes the source statements in a text file to produce a relocatable 
object file. 

• Produces a source listing (if requested) and provides you with control 
over the format of this listing. 

• Appends a cross-reference listing to the source listing (if requested). 

• Allows you to segment your code into sections. 

• Maintains an SPC (section program counter) for each section of object 
code. 

• Defines and references global symbols. 

• Assembles conditional blocks. 

Topics in this section include: 


Section Page 

4.1 Assembler Development Flow .4-2 

4.2 Invoking the Assembler .4-3 

4.3 Specifying Alternate Directories for Assembler Input .4-4 

4.4 Source Statement Format .4-6 

4.5 Constants .4-8 

4.6 Character Strings .4-11 

4.7 Symbols .4-11 

4.8 Expressions.4-12 

4.9 Source Listings . 4-16 

4.10Cross-Reference Listings...4-18 
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Assembler Description - Development Flow 


4.1 Assembler Development Flow 

Figure 4-1 illustrates the assembler's role in the assembly language develop¬ 
ment flow. The assembler accepts assembly language source files as input; it 
also accepts assembly language files created by the C compiler. 


Macro 


i 

i 

Assembler 


C Source 

Source 

Files 

- 

i 

i 

1 

Source 

V-| 

1 

1 

1 








Software 


XDS 

Emulator 

Simulator 


TMS34010 


Development 

Board 



Figure 4-1. Assembler Development Flow 
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Assembler Description - Invoking the Assembler 


4.2 Invoking the Assembler 

To invoke the assembler, enter: 

gspa input file [object file [listing file]] [-options] 

gspa is the command that invokes the assembler. 

input file names the assembler source file. If you do not supply an exten¬ 
sion, the assembler assumes that the input file has the default 
extension .asm. If you do not supply an input filename when 
you invoke the assembler, the assembler will prompt you for one. 

object file names the object file that the assembler creates. If you do not 
supply an extension, the assembler uses .obj as a default exten¬ 
sion. If you do not supply an object file, the assembler creates a 
file that uses the input filename with the .obj extension. 

listing file names the listing file that the assembler creates. If you do not 
supply an extension, the assembler uses Jst as a default exten¬ 
sion. If you do not supply a name for a listing file, the assembler 
does not create one , unless you use the -I option. In this case, 
the assembler uses the input file name with the .1st extension. 

option identifies the assembler options that you want to use. Case is 
insignificant for assembler options. Options can appear any¬ 
where on the command line; precede each option with a hyphen 
(-). You can string the options together; for example, -Ic is 
equivalent to -I -c. Valid assembler options include: 

-I (lowercase "L") produces a listing file. 

-i specifies a directory name where the assembler can find files 
named by the .copy, .include, or .mlib directives. The format 
of the -i option is -xpathname. You can specify up to 10 di¬ 
rectories in this manner; each pathname must be preceded 
by the -i option. 

-x produces a cross-reference table and appends it to the end 
of the listing file. If you did not request a listing file, the as¬ 
sembler creates one anyway, but the listing will only contain 
the cross-reference table. 

-c makes case insignificant in the source file. For example, the 
symbols ABC and abc will be equivalent. If you do not use 
this option , case is significant. 

-s Put all defined symbols in the object file's symbol table. 

-q (quiet) suppresses the banner and all progress information. 

-b makes blanks significant. This option provides compatibility 
with older code in which a blank terminated the operand 
field, and thus began the comment field. 

-h allows hexadecimal constants to use the format >nnn. This 
option provides compatibility with older code that uses this 
format. Note that this format limits the number of legal op¬ 
erators for expressions. 
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Assembler Description - Alternate Directories 


4.3 Specifying Alternate Directories for Assembler Input 

The .copy and .include directives tell the assembler to read source statements 
from another file and the .mlib directive names a library that contains macro 
definitions. Section 5, Assembler Directives, provides examples of the .copy, 
.include, and .mlib directives. The syntax for these directives is: 

.copy " filename " 

.include "filename” 

.mlib " filename " 

The filename names a copy/include file that the assembler reads statements 
from or a macro library that contains macro definitions. The filename may be 
a complete pathname or a filename with no path information. If you provide 
a pathname, the assembler uses that path and does not look for the file in any 
other directories. If you do not provide path information, the assembler 
searches for the file in: 

1) The directory that contains the current source file. (The current source 
file refers to the file that is begin assembled when the .copy, .include, or 
.mlib directive is encountered.) 

2) Any directories named with the -i assembler option. 

3) Any directories set with the environment variable A—DIR. 

You can augment the assembler's directory search algorithm by using the -i 
assembler option or the assembler's environment variable. A—DIR. 

4.3.1 -i Assembler Option 

The -i assembler option names an alternate directory that contains copy/in¬ 
clude files or macro libraries. The format of the -i option is: 

gspa -i pathname source-file 

You can use up to 10 -i options per invocation; each -i option names one 
pathname. In assembly source, you can now use the .copy, .include, or .mlib 
directives without specifying any path information for the copy/include file or 
macro library. If the assembler doesn't find the file in the directory that con¬ 
tains the current file, it searches the paths provided by the -i options. 

Assume that a file called source. asm is in the current directory; source. asm 
contains the following directive statement: 

.copy "copy.asm" 

The complete path/filename for copy.asm is: 

• c : \gsp\f iles\copy. asm (DOS), 

• [ gsp. files ] copy. asm (VMS), or 

• /gsp/f iles/copy. asm (UNIX). 

This is how you invoke the assembler: 

DOS: gspa -ic : \gsp\files source.asm 

VMS: gspa -i [gsp. files] source, asm 

UNIX: gspa -i/gsp/files source.asm 
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The assembler first searches for copy.asm in the current directory, because 
source.asm is in the current directory. Then, the assembler searches in the 
directory named with the -i option. 

4.3.2 Environment Variable (A—DIR) 

An environment variable is a system symbol that you define and assign a string 
to. The assembler uses an environment variable named A— DIR to name al¬ 
ternate directories that contain copy/include files or macro libraries. The 
command for assigning the environment variable is: 

DOS: set A— D[R=pathname;another pathname ... 

VMS: assign A—DIR " pathname; another pathname ... " 

UNIX: setenv A— DIR ”pathname;another pathname ... " 

The pathnames are directories that contain copy/include files or macro li¬ 
braries. You can separate the pathnames with a semicolon or with blanks. In 
assembly source, you can now use the .copy, .include, or .mlib directives 
without specifying any path information. If the assembler doesn't find the file 
in the parent directory or in directories named by -i, it searches the paths 
named by the environment variable. 

For example, assume that a file called source. asm contains these statements: 

.copy "copyl.asm" 

.copy "copy2.asm" 

Assume that the complete path and file information for these copy files is: 

• c: \340\f iles\copyl. asm and c: \gsys\copy2 . asm (DOS), 

• [ 340 . f iles ] copyl. asm and [ gsys ] copy2 . asm (VMS), or 

• /340/files/copy 1. asm and /gsys/copy2 . asm (UNIX). 

This is how you set the environment variables and invoke the assembler: 

DOS: set A_DIR=c:\gsys;c:\exec\files;c:\test 

gspa -ic:\340\flies source.asm 

VMS: assign A_DIR "[gsys];[exec.files];[test]" 

gspa -i/340/files source.asm 

UNIX: setenv A_DIR "/gsys;/exec/files;/test" 
gspa -i/340/files source.asm 

The assembler first searches for copyl. asm and copy2 . asm in the current di¬ 
rectory, because source.asm is in the current directory. Then, the assembler 
searches in the directory named with the -i option, and finds copyl.asm. Fi¬ 
nally, the assembler searches the directory named with A—DIR and finds 

copy2.asm. 

Note that the environment variable remains set until you reboot the system or 
reset the variable by entering: 

DOS: set A_DIR= 

VMS: deassign A—DIR 

UNIX: setenv A—DIR "" 
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Assembler Description - Source Statement Format 


4.4 Source Statement Format 

TMS34010 assembly language source programs consist of source statements 
that may contain assembler directives, assembly language instructions, macro 
directives, and comments. Source statement lines may be as long as the 
source file format allows. The assembler reads up to 200 characters per line. 
If a statement contains more than 200 characters, the assembler truncates the 
line and issues a warning. 

The next several lines show examples of source statements: 

SYM .set 0A5h ; Symbol SYM = 0A5h 

Begin: ADDI SYM+5,A1 ; Add (SYM+5) to the contents of A1 

MOVE A1 , A2 ; Move contents of A1 to A2 

A source statement may contain four ordered fields. The general syntax for 
source statements is: 

[label[:]] mnemonic [operand list] [comment] 
where: 

• Statements must begin with a label, a blank, or a comment indicator. 

• Labels are optional; if used, they must begin in column 1. 

• One or more blanks must separate each field. (Note that tab characters 
are equivalent to blanks.) 

• Comments are optional. Comments that begin in column 1 can begin 
with an asterisk or a semicolon (* or ;), but comments that begin in any 
other column must begin with a semicolon. 

4.4.1 Label Field 

Labels are optional for all assembly language instructions and for most (but 
not all) assembler directives. A label must begin in column 1 of a source 
statement. A label can contain up to 32 alphanumeric characters (A-Z, a-z, 
0-9, —, and $). Labels are case sensitive, and the first character cannot be a 
number. A label can be followed by a colon (:); the colon is not treated as 
part of the label name. If you don't use a label, then the first character position 
must contain a blank or a comment indicator. 

When you use a label, its value is the current value of the section program 
counter (the label points to the statement it's associated with). If, for example, 
you use the .byte directive to initialize several bytes, a label would point to the 
first byte. In the following example, the label Start has the value 40h. 


0009 

00000030 


* Assume some 

other code has been assembled 

0010 

00000040 

0A 

Start: .byte 

OAh,3,7 


00000048 

03 



00000050 

07 




A label on a line by itself is a valid statement. It assigns the current value of 
the section program counter to the label - this is equivalent to the following 
directive statement: 

label .set $ ; ($ is the current value of the SPC) 
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When a label appears on a line by itself, it usually points to the instruction on 
the next line (the SPC is not incremented): 

0003 00000050 Here: 

0004 00000050 03 .byte 3 


Since the TMS34010 is a bit-addressable machine, some operations (such as 
.field) can increment the SPC in a way that may not align it to point to a word 
boundary. Other directives (such as .even) automatically realign the SPC. If 
a statement that contains only a label is followed by a statement that realigns 
the SPC, then the label will not point to the statement that follows it. In this 
example, a .field directive "misaligns" the SPC; the label does not point to the 
statement that contains the .even directive. 


0001 00000000 

0002 00000010 03 

0003 00000012 Label: 

0004 00000020 


.space 16 
.field 3,2 

; Label = 12h 

.even ; SPC is now 20h 


4.4.2 Mnemonic Field 

The mnemonic field follows the label field. The mnemonic field cannot start 
in column 1, or it would be interpreted as a label. The mnemonic field can 
contain one of the following opcodes: 

• Machine-instruction mnemonic (such as ADD, FILL, MOVE) 

• Assembler directive (such as .data, .align, .set) 

• Macro directive (such as $MACRO, $LOOP, $NOLOOP) 

• A macro invocation 


4.4.3 Operand List 

The operand field is a list of operands that follows the mnemonic field. An 
operand can be a constant (see Section 4.5), a symbol (see Section 4.7), or 
a combination of constants and symbols in an expression (see Section 4.8). 
You must separate operands with commas. 


4.4.4 Comment Field 

A comment can begin in any column, and extends to the end of the source 
line. A comment can contain any ASCII character, including blanks. Its con¬ 
tents are listed in the assembly source listing but do not affect the assembly. 

A source statement that contains only a comment is valid. If it begins in col¬ 
umn 1, it can start with a ; or a *. Comments that begin anywhere else on the 
line must begin with a The * symbol only designates a comment if it ap¬ 
pears in column 1. 
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4.5 Constants 

The assembler supports seven types of constants: 

• Binary integer constants, 

• Octal integer constants, 

• Decimal integer constants, 

• Hexadecimal integer constants, 

• XY constants, 

• Character constants, and 

• Assembly-time constants. 

The assembler maintains each constant internally as a 32-bit quantity. The 
assembler determines the length of variable-length instructions (such as 
ADDI) so they can be implemented efficiently. The assembler will use a 16-bit 
or 32-bit operand, depending on the magnitude of the operand. 

Note that constants are not sign extended, they are right justified. For 
example, the constant OFFFFH is equal to OOOOFFFF-je or 65,535io; it does 
not equal -1. 


4.5.1 Binary Integers 

A binary integer constant is a string of up to 32 binary digits (Os and Is) fol¬ 
lowed by the suffix B (or b). If less than 32 digits are specified, the assembler 
right-justifies the bits. Examples of valid binary constants include: 

00000000B Constant equal to 0 

0100000b Constant equal to 32 -|q (20-| 6) 

01b Constant equal to 1 

11111000B Constant equal to 248-] o (0F8-|6) 


4.5.2 Octal Integers 

An octal integer constant is a string of up to 12 octal digits (0 through 7) 
followed by the suffix Q(or q). Examples of valid octal constants include: 


10Q 

Constant equal to 

100000Q 

Constant equal to 

226Q 

Constant equal to 


810 (8-j 6) 

32,768-1 o (8000 16 ) 
150 10 (96 16 ) 
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4.5.3 Decimal Integers 

A decimal integer constant is a string of decimal digits, ranging from 
-2,147,483,647 to 4,294,967,295. Examples of valid decimal constants in¬ 
clude: 

1000 Constant equal to IOOOiq (3E8-| 6) 

-32768 Constant equal to -32,768io (8000i6) 

25 Constant equal to 25io 9l 6) 

4.5.4 Hexadecimal Integers 

A hexadecimal integer constant is a string of up to 8 hexadecimal digits fol¬ 
lowed by the suffix H (or h). Hexadecimal digits include the decimal values 
0-9 and the letters A-F and a-f. A hexadecimal constant must begin with a 
decimal value (0-9). If less than 8 hexadecimal digits are specified, the as¬ 
sembler right-justifies the bits. Examples of valid hexadecimal constants in¬ 
clude: 

78h Constant equal to 1 20^0 (0078i 6) 

OFh Constant equal to 1 5io (000Fl 6) 

37ACH Constant equal to 14,252 -iq (37AC-ie) 

4.5.5 XY Constants 

An XY constant is a constant in the form [Y-expression, X-expression]. The 
X-expression and Y-expression can be any legal, well-defined 16-bit ex¬ 
pression in the range [-32767, -32767] to [65535, 65535]. The Y part and 
the X part are concatenated to form a 32-bit field; the Y part occupies the 16 
MSBs of the field and the X part occupies the 16 LSBs. Examples of valid 
XY constants include: 

[1 +2, 4] Constant equal to 00030004^ 6 

[- 1 , 0 ] Constant equal to FFFFOOOO 16 

[lOq, 101b] Constant equal to 00080005ie 

[ 7 ab 7 , 7 cd 7 ] Constant equal to 62616463-J6 

[OFh, OCh] Constant equal to OOOFOOOC-ie 
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4.5.6 Character Constants 

A character constant is a string of 1 to 4 characters enclosed in single quotes. 
The characters are represented internally as 8-bit ASCII characters. Two 
consecutive single quotes are required to represent each single quote within 
a character constant. A character constant consisting only of two single 
quotes (no character) is valid and is assigned the value 0. If less than 4 
characters are specified, the assembler right-justifies the bits. Examples of 
valid character constants include: 

'ab' Represented internally as 00006261 

X' Represented internally as 00000043-16 

"'D' Represented internally as 00004427-J6 

'abed' Represented internally as 64636261 16 

Note the difference between character constants and character strings (Sec¬ 
tion 4.6 discusses character strings). A character constant represents a single 
integer value; a string is a list of characters. 

4.5.7 Assembly-Time Constants 

If you use the .set directive to assign a value to a symbol, the symbol becomes 
a constant. In order to use this constant in expressions, the value assigned to 
it must be absolute. For example, 

val .set 3 

MOVI val, A0 

If you assign an integer constant to a symbol, then the symbol can only be 
used as an integer constant. 

You can also use .set to assign symbolic names constants for register names. 
In this case, the symbol becomes a synonym for the register: 

COLORO .set B8 

MOVI 1111111lh, COLORO 
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4.6 Character Strings 

A character string is a string of characters enclosed in double quotes. Double 
quotes within character strings are represented by two consecutive double 
quotes. The maximum length of a string varies, and is defined for each direc¬ 
tive that requires a character string. Characters are represented internally as 
8 -bit ASCII characters. Appendix E lists valid characters. 

Examples of valid character strings include: 

"sample program" Defines a 1 4-character string, sample program 
"PLAN ""C""" Defines an 8-character string, plan ”C” 

Character strings are used for: 

• Filenames (as in .copy "filename") 

• Section names (as in .sect ’’section name”) 

• Data initialization directives (as in .byte "charstring”) 


4.7 Symbols 

Symbols are used as labels and in operands. A symbol name is a string of up 
to 32 alphanumeric characters (A-Z, a-z, 0-9, $, and —). The first character in 
a symbol cannot be a number; symbols cannot contain embedded blanks. The 
symbols you define are case sensitive; for example, the assembler will recog¬ 
nize ABC, Abe, and abc as three unique symbols. (You can override this with 
the -c assembler option.) These types of symbols are valid only during the 
assembly in which they are defined. 

Symbols that are used as labels become symbolic addresses that are associ¬ 
ated with locations in the program. Labels must be unique; do not re-use 
them for other statements. Mnemonic opcodes and assembler directive names 
(without the . prefix) are valid label names. 

Symbols that are used in operands must be defined in the assembly by ap¬ 
pearing as labels or as operands of a .global, .set, or .bss directive. 

The assembler has several predefined symbols, including: 

• $, the dollar sign character, which represents the current value of the 
section program counter. 

• SP or sp, the stack pointer symbol, which refers to the 16th register in 
either register file A or B. 

• Register symbols, which have the form A/7, a/7, Bn, or bn, where n is 
0-14. 
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4.8 Expressions 

An expression is a constant, a symbol, or a series of constants and symbols 
separated by arithmetic operators. The range of valid expression values is 
-2,147,483,647 to 4,294,967,295. 

Three main factors influence the order of expression evaluation: 

• Parentheses: Expressions that are enclosed in parentheses are always 
evaluated first. 

Example: 8/(4/2) = 4, but 8/4/2 = 1 

Note that you cannot substitute braces ( {} ) or brackets ( [] ) for pa¬ 
rentheses. 

• Precedence groups: Operators (listed in Table 4-1) are divided into 
four precedence groups. When the order of expression evaluation is not 
determined by parentheses, the highest-precedence operation is evalu¬ 
ated first. 

Example: 8 + 4/2 = 10 (4/2 is evaluated first) 

• Left-to-right evaluation: When parentheses and precedence groups 
do not determine the order of of expression evaluation, the expressions 
are evaluated from left to right. (Note that the highest precedence group 
is evaluated from right to left.) 

Example: 8/4*2 = 4, but 8/(4*2) = 1 


4.8.1 Operators 

Table 4-1 lists the operators than can be used in expressions. They are listed 
according to precedence group. 

Table 4-1. Operators 


Group 1 (Highest Precedence) 
Right-to-Left Evaluation 

Group 3 

Left-to-Right Evaluation 

+ 

Unary plus (positive expression) 

+ 

Addition 

- 

Unary minus (negative expression) 

- 

Subtraction 


1 s complement 


Bitwise exclusive-OR 



| 

Bitwise OR 



& 

Bitwise AND 


Group 2 

Group 4 (Relational Operators) 


Left-to-Right Evaluation 


Left-to-Right Evaluation 

* 

Multiplication 

< 

Less than 

/ 

Division 

> 

Greater than 

% 

Modulo 

< = 

Less than or equal to 

< < 

Left shift 

> = 

Greater than or equal to 

> > 

Right shift 

= 

( = = ) Equal to 



! = 

Not equal to 


Note: Operators in parentheses indicate an alternate form. 
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4.8.2 Expression Overflow or Underflow 

The assembler checks for overflow and underflow conditions when arithmetic 
operations are performed at assembly time. The assembler will issue a Value 
Truncated warning whenever an overflow or underflow occurs. The assem¬ 
bler does not check for overflow or underflow in multiplication. 

4.8.3 Well-Defined Expressions 

Some assembler directives require well-defined expressions as operands. 
Well-defined expressions contain only symbols or assembly-time constants 
that are defined before they are encountered in the expression. The evaluation 
of a well-defined expression must be absolute. 

An example of a well-defined expression is: 

lOOOh+x Where x has been previously defined as an absolute symbol. 

4.8.4 Conditional Expressions 

The assembler supports relational operators that can be used in any ex¬ 
pression; they are especially useful for conditional assembly. Relational oper¬ 
ators include: 


Equal 

!= Not equal 

Equal 

< Less than 

Less than or equal 

> Greater than 

Greater than or equal 



These operations have the lowest precedence; however, each has the same 
precedence within the group, so they are evaluated left to right. Conditional 
expressions evaluate to 1 if true and 0 if false. 

4.8.5 Relocatable Symbols and Legal Expressions 

Table 4-2 summarizes valid operations on absolute, relocatable, and external 
symbols. An expression cannot multiply or divide by a relocatable or external 
symbol. An expression cannot contain unresolved symbols that are relocata¬ 
ble with respect to different sections. 

Table 4-2. Expressions with Absolute and Relocatable Symbols 


A is... 

B is... 

Results of A+B are... 

Results of A-B are... 

absolute 

absolute 

absolute 

absolute 

absolute 

external 

external 

illegal 

absolute 

relocatable 

relocatable 

illegal 

relocatable 

absolute 

relocatable 

relocatable 

relocatable 

relocatable 

illegal 

absolute - ! - 

relocatable 

external 

illegal 

illegal 

external 

absolute 

external 

external 

external 

relocatable 

illegal 

illegal 

external 

external 

illegal 

illegal 


t A and B must be in the same section, otherwise this is illegal. 
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Here are some examples of expressions that use relocatable and absolute 
symbols. These examples use four symbols that are defined as follows: 


.global extern—1 
intern—1: .word "'D' 

LABI: .set 2 

intern—2: 


Defined in an external module 
Relocatable, defined in current module 
LABI = 2 

Relocatable, defined in current module 


• Example 1: 

The statements in this example use an absolute symbol, labi. The first 
statement puts the value 51 into register AO. The second statement puts 
the value 27 into register AO. 

MOVI LABI + ((4+3) * 7) , AO ; AO = 51 

MOVI LABI + 4 + 3 * 7, AO ; AO = 27 


• Example 2: 

All legal expressions can be reduced to one of two forms: 

relocatable symbol ± absolute symbol 

or 

absolute value 

Unary operators can only be applied to absolute values; they cannot be 
applied to relocatable symbols. Expressions that cannot be reduced to 
contain only one relocatable symbol are illegal. The first statement in the 
following example is legal; the statements that follow it are invalid. 

MOVI extern—1 - 10, AO ; Legal 

MOVI 10-extern—1, AO ; Can't negate reloc. symbol 

MOVI -(intern—1), AO ; Can’t negate reloc. symbol 

MOVI extern—1/10, AO ; / isn't an additive operator 

MOVI intern—1 + extern—1, AO ; Multiple relocatables 

• Example 3: 

The first statement below is legal; although intern_l and intern_2 
are relocatable, their difference is absolute because they're in the same 
section. Subtracting one relocatable symbol from another reduces the 
expression to relocatable symbol + absolute value. The second state¬ 
ment is illegal because the sum of two relocatable symbols is not an 
absolute value. 

MOVI intern—1 - intern—2 + extern—1, AO ; Legal 

MOVI intern—1 + intern—2 + extern—1, AO ; Illegal 

• Example 4: 

An external symbol's placement in an expression is important to ex¬ 
pression evaluation. Although the statement below is similar to the first 
statement in the previous example, it is illegal. This is because of left- 
to-right operator precedence; the assembler attempts to add intern_l 
to extern—1 . 

MOVI intern—1 + extern—1 - intern—2, AO ; Illegal 
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4.9 Source Listings 

A source listing shows source statements and the object code they produce. 
To obtain a listing file, invoke the assembler with the -I (lowercase "L") op¬ 
tion. 

At the top of each source listing page are two banner lines, a blank line, and 
a title line. Any title supplied by a .title directive is printed on this line; a page 
number is printed to the right of the title. If you don't use the .title directive, 
the title area is left blank. The assembler inserts a blank line below the title 
line. 

Each line in the source file produces a line in the listing file that contains a 
source statement number, an SPC value, the object code assembled, and the 
source statement. A source statement may produce more than one word of 
object code. The assembler prints the SPC value and object code on a sepa¬ 
rate line for each additional word. Each additional line is printed immediately 
following the source statement line. 

12 3 4 

0015 00000000' FloatA .set $ ; Program entry point 

0016 00000000 01E0 PUSHST ; Push status register 

0017 00000010 098F MMTM SP,A0,A14 ; Save registers used 

Field 1 Source Statement Number. The source statement number is a 
4-digit decimal number. The assembler numbers source lines as it 
encounters them in the source file; some statements increment the 
line counter but are not listed (for example, .title statements and 
statements following a .nolist are not listed). The difference be¬ 
tween two consecutive source line numbers indicates the number 
of source lines entered that are not listed. Source lines generated 
by a macro call, a .copy directive, or an .include directive are re¬ 
numbered starting at 0001. The original sequence continues after 
the copying or macro expansion is complete. The assembler pre¬ 
cedes the line numbers of copied files with a letter code to identify 
the level of copying. An A indicates the first level, B indicates a 
second level, etc. 

Field 2 Section Program Counter. This field contains the section program 
counter, or SPC, value (hexadecimal). Each section (.text, .data, 
.bss, and named sections) maintains a separate SPC. Some direc¬ 
tives do not affect the SPC; they leave this field blank. 

Field 3 Object Code. This field contains the hexadecimal representation of 
the object code. All machine instructions and directives use this 
field to list object code. This field also indicates the relocation type 
by appending one of the following characters to the end of the field: 

! Undefined external reference 
' .text relocatable 
" .data relocatable 
+ .data relocatable 
- .bss, .usect relocatable 
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Field 4 Source Statement Field. This field contains the characters of the 
source statement as they were scanned by the assembler. The as¬ 
sembler accepts a maximum line length of 200 characters. Spacing 
in this field is determined by the spacing in the source statement. 


GSP COFF Assembler, Version x.xx, 86.200 Mon 

Mar 16 15:15:28 1987 

(c) Copyright 

1985, 1986 

, Texas Instruments Inc. 







PAGE 1 

0001 



***************************************************** 

0002 



* This function 

takes the ABS of 

a single-precision, 

0003 



* IEEE-format floating-point number. The value to be 

0004 



* ABS is popped 

off the stack as 

described in the 

0005 



* TMS34010 C Compiler User's Guide. The returned ABS 

0006 



* number is pushed onto the stack 

as also specified 

0007 



* in the guide. 



0008 



**************************************************** l 

0009 



* 



0010 



. f ile 

"FloatA" 


0011 



* 



0012 



* Define as a subroutine 


0013 



* 



0014 



.global 

FloatA 


0015 


00000000' 

FloatA .set 

$ 

Program entry point 

0016 

00000000 

01E0 

PUSHST 


Push status register 

0017 

00000010 

098F 

MMTM 

SP,A0,A14 ; 

Save registers used 


00000020 

8002 




0018 

00000030 

0541 

SETF 

1,0,0 


0019 

00000040 

5600 

XOR 

A0,A0 ; 

Clear the sign bit 

0020 

00000050 

BOOE 

MOVE 

A0,*A14(-1),0 ; 

Put result on stack 


00000060 

FFFF 




0021 

00000070 

09AF 

MMFM 

SP,A0,A14 ; 

Restore registers 


00000080 

4001 




0022 

00000090 

01C0 

POPST 

; 

Restore status 

0023 

000000A0 

0960 

RETS 



0024 



. end 



No Errors, No 

Warnings 





Figure 4-2. Sample Assembler Listing 
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4.10 Cross-Reference Listings 

A cross-reference listing shows symbols and their definitions. To obtain a 
cross-reference listing, invoke the assembler with the -x option or use the 
.option directive. The assembler will append the cross-reference to the end 
of the source listing. 


GSP COFF Assembler, 

Version x.xx, 86.200 



Mon 

Mar 16 15:15:28 

1987 

(c) Copyright 1985, 

1986, Texas Instruments Inc. 









PAGE 

2 

LABEL 

VALUE 

DEFN 

REF 




INTO 

00000002+ 

15 

2 




INTI 

00000004+ 

16 

2 




INT2 

00000006+ 

17 

2 




ISRO 

REF 



4 

15 


ISR1 

REF 



4 

16 


ISR2 

REF 



4 

17 


RESET 

00000000+ 

13 

2 




RINT 

00000002+ 

26 

3 




TINT 

00000000+ 

25 

3 




VECS 

00000006+ 

28 

3 




XINT 

00000004+ 

27 






Figure 4-3. Cross-Reference Listing Format 


• The label column contains each symbol that was defined or referenced 
during the assembly. 

• The value column contains an 8-digit hexadecimal number which is the 
value assigned to the symbol or a name that describes the symbol's at¬ 
tributes. A value may be followed by either a character that describes the 
symbol attributes. Table 4-3 lists these characters and names. 

• The definition (DEFN) column contains the statement number in 
which the symbol is defined. This column is blank for undefined sym¬ 
bols. 

• The reference (REF) column lists the line numbers of statements that 
reference the symbol. A blank in this column indicates that the symbol 
was never used. 


Table 4-3. Symbol Attributes 


Character 
or Name 

Meaning 

REF 

External reference (global symbol) 

UNDF 

Undefined 

' 

Symbol defined in a .text section 

" 

Symbol defined in a .data section 

+ 

Symbol defined in a .sect section 

- 

Symbol defined in a .bss or .usect section 
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Assembler Directives 


Assembler directives supply program data and control the assembly process. 
Assembler directives allow you to: 

• Assemble code and data into specified sections 

• Reserve space in memory for uninitialized variables 

• Control the appearance of listings 

• Initialize memory 

• Assemble conditional blocks 

• Define global variables 

• Specify libraries that the assembler can obtain macros from 

• Examine symbolic debugging information 

This section is divided into two parts: the first part (Sections 5.1 through 5.7) 
describes the directives according to function, and the second part (Section 
5.8) is an alphabetical reference. This section includes the following topics: 

Section Page 

5.1 Directives Summary. 5-2 

5.2 Sections Directives .5-4 

5.3 Directives that Initialize Constants .5-6 

5.4 Directives that Align the Section Program Counter .5-9 

5.5 Directives that Format the Output Listing .5-11 

5.6 Conditional Assembly Directives . 5-12 

5.7 Directives that Reference Other Files.5-13 

5.8 Directives Reference.5-14 

The TMS34010 C compiler uses several directives for symbolic debugging. 

Unlike other directives, symbolic debugging directives are not used in most 
assembly language programs. Appendix B discusses these directives; they are 
not discussed in this section. 
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5.1 Directives Summary 

Table 5-1 summarizes the assembler directives. Note that all source state¬ 
ments that contain a directive may have a label and a comment. To improve 
readability, they are not shown as part of the directive syntax. 

Table 5-1. Directives Summary 


Directives that Affect the Current Section 

Mnemonic and Syntax 

Description 

.bss symbol \ size in bits [, word alignment flag] 

Reserve size bits in a named (uninitialized) section 

.data 

Assemble into the .data (initialized data) section 

.sect "section name" 

Assemble into a named (initialized) section 

.text 

Assemble into the .text (executable code) section 

symbol .usect "section name", size in bits 
[, word alignment flag] 

Assemble into the .text (executable code) section 

| Directives that Initialize Constants j 

Mnemonic and Syntax 

Description 

.bes size in bits 

Reserve size bits in the current section; note that 
a label points to the last bit of the reserved space 

.byte value j [, value n ] 

Initialize one or more successive bytes in the cur¬ 
rent section 

.double floating-point value 

Initialize a 64-bit, double-precision, floating-point 
constant 

.field value [, size in bits] 

Initialize a variable-length field 

.float floating-point value 

Initialize a 32-bit, single-precision, floating-point 
constant 

.int value j [, ..., va!ue n ] 

Initialize one or more 32-bit integers 

.long value j [, value n ] 

Initialize one or more 32-bit integers 

symbol .set value 

Initialize an assembly-time constant 

.space size in bits 

Reserve size bits in current section; note that a la¬ 
bel points to the first bit in the reserved space 

.string "stringj” [, "string n "] 

Initialize one or more text strings 

.word value i [, ..., value n ] 

Initialize one or more 16-bit integers 

| Directives that Align the Section Program Counter (SPC) | 

Mnemonic and Syntax 

Description 

.align 

Align the SPC on 32-word boundary 

.even 

Align the SPC on word (16-bit) boundary 

Directives that Format the Output Listing | 

Mnemonic and Syntax 

Description 

.length page length 

Set the page length of the source listing 

.list 

Restart the source listing 

.mlist 

Allow macro listings (default) 

.mnolist 

Inhibit macro listings 
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Table 5-1. Directives Summary (Concluded) 


Directives that Format the Output Listing (continued) 

Mnemonic and Syntax 

Description 

.nolist 

Stop the source listing 

.option {B \ D \ F \ L \ M \ T \X} 

Select output listing options 

.page 

Eject a page in the source listing 

.title "string" 

Print a title in the listing page heading 

.width page width 

Set the page width of the source listing 

Conditional Assembly Directives 

Mnemonic and Syntax 

Description 

.if expression 

Begin conditional assembly 

.else 

Optional conditional assembly 

.endif 

End conditional assembly 

Directives that Reference Other Files 

Mnemonic and Syntax 

Description 

.copy ["]filename["] 

Include source statements from another file 

.def symbolj [, symbol n ] 

Identify one or more symbols that are defined in 
the current module and used in another module 

.global symbol j [, .... symbol n ] 

Identify one or more global (external) symbols 

.include ["]fi!ename["] 

Include source statements from another file (simi¬ 
lar to .copy, but the included statements are not 
listed) 

.mlib ["]filename["] 

Define macro library 

.ref symbol / [, ..., symbol n ] 

Identify one or more symbols that are used in the 
current module but defined in another module 

Miscellaneous Directives 

Mnemonic and Syntax 

Description 

.end 

Program end 

Symbolic Debugging Directives t 

Mnemonic and Syntax 

Description 

.block beginning line number 

Begin a C block 

.endblock ending line number 

End a C block 

.endfunc ending line number 

End a function definition 

.eos 

End a structure, enumeration, or union definition 

.etag name, size 

Begin an enumeration definition 

.file "filename" 

Define a program identifier 

.func beginning line number 

Begin a function definition 

.line line number [, address] 

Specify the line number of a C source statement 

.member name, value [, type, storage class, 
size, tag, dims] 

Define a member of a structure, enumeration, or 
union 

.stag name, size 

Begin a structure definition 

.sym name, value [, type, storage class, 
size, tag, dims] 

Specify symbolic debug information for a global 
variable, local variable, or a function 

.utag name, size 

Begin a union definition 


t Appendix B discusses symbolic debugging directives 
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Assembler Directives - Sections Directives 


5.2 Sections Directives 

Section 3 discusses COFF sections in detail. Five directives associate the 
various portions of an assembly language program with the appropriate sec¬ 
tion: 


• The .bss directive reserves space in the .bss section for variables. 

• The .usect directive reserves space in an uninitialized named section. 
The .usect directive is similar to the .bss directive, but it allows you to 
reserve space separately from the .bss section. 

• The .text directive identifies portions of code in the .text section. The 
.text section usually contains executable code. 

• The .data directive identifies portions of code in the .data section. The 
.data section usually contains initialized data. 

• The .sect directive creates an initialized named section and associates 
subsequent code or data with that section. 

Figure 5-1 shows how you can use section directives to associate code and 
data with the proper sections. This is an output listing; column 1 shows line 
numbers, and column 2 shows the section program counter. Each section has 
its own program counter, or SPC. When code is first placed in a section, its 
SPC equals 0. When you resume assembling into a section, its SPC will re¬ 
sume counting as if there had been no intervening code. 

After the code in Figure 5-1 is assembled, the sections contain the following: 

.text Initializes words with the values 1, 2, 3, 4, 5, 6, 7, and 8 

.data Initializes words with the values 9, 10, 11, 12, 13, 14, 15, 

and 16 

var—defs Initializes words with the values 17 and 18 

.bss Reserves 19 bits 

xy Reserves 20 bits 

Note that the .bss and .usect directives do not end the current section and 
begin a new section; they reserve the specified amount of space, and then the 
assembler resumes assembling code or data into the current section. 
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0001 



********************************************* 

0002 



* Begin assembling into the .text section * 

0003 



********************************************* 

0004 

00000000 


. text 


0005 

00000000 

0001 

. word 

1, 2 


00000010 

0002 



0006 

00000020 

0003 

.word 

3, 4 


00000030 

0004 



0007 





0008 



********************************************* 

0009 



* Begin assembling into the .data section * 

0010 



********************************************* 

0011 

00000000 


. data 


0012 

00000000 

0009 

. word 

9, 10 


00000010 

000A 



0013 

00000020 

000B 

.word 

11, 12 


00000030 

OOOC 



0014 





0015 



********************************************* 

0016 



* Start assembling into a named, initial- * 

0017 



* ized section, 

var_defs * 

0018 



********************************************* 

0019 

00000000 


. sect 

"var-defs" 

0020 

00000000 

0011 

.word 

17, 18 


00000010 

0012 



0021 





0022 



********************************************* 

0023 



* Resume assembling into the .data section * 

0024 



********************************************* 

0025 

00000040 


. data 


0026 

00000040 

OOOD 

. word 

13, 14 


00000050 

000E 



0027 





0028 

00000000 


. bss 

sym, 19 ; Reserve space 

0029 




; in .bss 

0030 

00000060 

000F 

. word 

15 ; Still in .data 

0031 





0032 



********************************************* 

0033 



* Resume assembling into the .text section * 

0034 



********************************************* 

0035 

00000040 


. text 


0036 

00000040 

0005 

. word 

5, 6 


00000050 

0006 



0037 





0038 

00000000 


usym .usect 

"xy", 20 ; Reserve space 

0039 




; in section xy 

0040 

00000060 

0007 

.word 

7 ; Still in .text 


Figure 5-1. Sections Directives Example 
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5.3 Directives that Initialize Constants 

Several directives initialize constants: 


• The .set directive equates a value with a symbol. This type of symbol 
is known as an assembly-time constant ; it can be used in the same 
manner as a numeric constant (for example, in expressions). 


This example defines a symbol named val and assigns the value 4 to it. 
The symbol val can then be used as a constant. 


0001 

0002 00000000 
00000008 
00000010 


0004 val .set 4 

04 .byte val, val*2, val+12 

08 
10 


Note that the .set directive produces no object code. 

• The .byte directive places one or more 8-bit values into consecutive 
bytes in the current section. The first byte is always aligned on an 8-bit 
boundary. 

• The .word directive places one or more 16-bit values into consecutive 
words in the current section. The first word is aligned on a 16-bit 
boundary. 

• The .int and .long directives place one or more 32-bit values into con¬ 
secutive locations in the current section. The first integer is aligned on 
a 16-bit boundary. 

• The .float and .double directives initialize floating-point numbers, 
.float initializes a 32-bit, single-precision value, and .double initializes a 
64-bit, double-precision value. 

• The .string directive places 8-bit characters from one or more character 
strings into consecutive bytes in the current section. The characters are 
maintained as 8-bit ASCII codes. 

Figure 5-2 compares the .byte, .word, .int, .long, .float, .double, and 
.string directives; for this example, assume the following code has been 
assembled: 

0003 


0004 

00000000 

AB 

. byte 

OABh, OCDh 


00000008 

CD 


0005 

00000010 

CDEF 

. word 

OCDEFh 

0006 

00000020 

12345678 

. int 

12345678h 

0007 

00000040 

12345678 

. long 

12345678h 

0008 

00000060 

E9C22CA9 

.float 

-1.0e2 5 

0009 

00000080 

16140148 

.double 

-1.0e25 


000000A0 

C5384595 



0010 

ooooooco 

47 

.string 

"GSP " 


000000C8 

53 




000000D0 

50 
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Word 

F 0 



Code 

.byte 

.word 

. int 
. long 
. float 

.double 
. string 


OABh, OCDh 
OCDEFh 

12345678h 

12345678h 

-1.0e25 

-1.0e25 

"GSP" 


Figure 5-2. Examples of Initialization Directives 


• The .bes and .space directives reserve a specified number of bits in the 
current section. The assemble fills these reserved bits with Os. 

When you use a label with .space, it points to the first reserved bit. 

- When you use a label with .bes, it points to the last reserved bit. 

Figure 5-3 shows an example of the .space and .bes directives. Assume 
the following code has been assembled for this example: 

0041 00000560 0100 .word lOOh, 200h 

00000570 0200 

0042 00000580 labell: .space 38h 

0043 000005FF label2: .bes 47h 

labell points to the first bit reserved by .space. Iabel2 points to the 
last bit reserved by .bes. 


580h 5B8h 5FFh 







1 . 



\ 

/\ 

/ 

V V 

38h bits reserved by 47h bits reserved by 

.space .bes 

-labell = 580h (first bit Iabel2 = 5FFh (last bit- 



reserved by .space) reserved by .bes) 

Figure 5-3. An Example of the .space and .bes Directive 
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Assembler Directives - Directives that Initialize Constants 


• The .field directive places a single value into a specified number of bits 
in the current word. You can pack multiple fields into a single word, and 
fields can span words; the assembler does not align the SPC before or 
after it puts the value into memory. 


Figure 5-4 shows how fields are packed into a word. For the example, 
assume the following code has been assembled: 


0004 

00000000 

08 

.byte 

8 


0005 

00000008 

0003 

.field 

3, 

2 

0006 

0000000A 

0009 

.field 

9, 

4 

0007 

0000000E 

0006 

.field 

6, 

7 

0008 

00000015 

002C 

.field 

44 , 

, 9 




7 6 5 4 3 2 

1 0 



0 

0 

0 

0 1 0 

0 0 1 

N — 

— 

— 

- V - 





8 bits 


9 8 





1 1 |d;; 

W 

IT 

o id; 

0 0 i 


2 bits 


D C B A _ 

1 00 1 1 1 1 10 0 0 0 t 0 0 Q] .field 9, 4 

4 bits 


141312 11 10 F E ___ 

0 0 0 0 1 1 0 [I 0 0 t 1 1 1 jO 0 0 0 f 0 0 0 1 .field 6, 7 

7 bits 


1D1C1B1A1918 171615 

000101 1 0 QlO 0 Q 0 1 1 Q|1 0 Q 1 1 T. 1 j 0 0 0 0 1 0 0 0] .field 44, 9 
9 bits 

Figure 5-4. An Example of the .field Directive 
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Assembler Directives - Directives that Align the SPC 


5.4 Directives that Align the Section Program Counter 

Several directives automatically align the SPC; for example, the .word directive 
will align the SPC if necessary so that the initialized word is aligned on a 
16-bit boundary. The assembler also supports two directives that allow you 
to explicitly align the SPC on a word or cache boundary: 

• The .even directive aligns the section program counter on a 16-bit 
boundary. After assembling a .byte, .field, .space, or .bes directive, the 
SPC may not be aligned on a 16-bit boundary. You can use the .even 
directive to force the assembler to align the SPC on the next word 
boundary; the assembler fills the space between the current SPC and the 
new SPC with Os. If the SPC is already aligned on a word boundary, the 
.even directive does not affect the SPC. 

Figure 5-5 shows how the .even directive aligns the SPC. Assume the 
following code has been assembled: 


0001 



* Part 1 



0002 

00000210 

0001 


.field 

1, 2 

0003 

00000212 

0003 


.field 

3 f 4 

0004 

00000216 

0006 


.field 

6, 3 

0005 

00000220 



. even 


0006 



* Part 2 



0007 

00000220 

08 


.byte 

8 

0008 

00000228 



.space 

lOh 

0009 

00000240 



. even 



In part 1, 9 bits of a word are filled by .field directives. The .even direc¬ 
tive fills the remainder of the word with Os and aligns the SPC on the 
next 16-bit boundary. In part 2, 8 bits of a word are filled by a .byte 
directive; the remaining 8 bits, and 8 bits of the next word, are filled by 
the .space directive. The .even directive fills the remainder of the second 
word with Os and aligns the SPC on the next 16-bit boundary. 

220h 210h 

(a) Part 1 . [ 0000000(1 1000110 i;-f . 


Bits filled with Os, Filled by .field 

SPC aligned by .even 


(b) Part 2 


240h 220h 

"[000000 0| 0 0 1 o oof 


Bits filled with Os, Filled by .byte 

SPC aligned by .even and .space 


Figure 5-5. An Example of the .even Directive 


• The .align directive aligns the SPC at the beginning of the next block 
of 32 16-bit instruction words. If the space between the current SPC 
and the new SPC is 3 words or less, the assembler fills this space with 
NOPs; otherwise, it inserts a jump instruction to the new SPC and fills 
the intervening space with NOPs. 
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Assembler Directives - Directives that Align the SPC 


Figure 5-6 shows an example that uses the .align directive. In this example, 
the SPC initially points to address 140h. After assembling the .align directive, 
the SPC points to the next 32-word boundary (address 200h). Assume the 
following code has been assembled: 

0008 00000120 AA .byte OAAh 

0009 00000130 0056 .word 56h, 23q 

00000140 0013 

0010 00000200 .align 

0011 00000200 9801 MOVE *A0 +, *A1+ 



after assembling 
an .align directive 


Figure 5-6. An Example of the .align Directive 


The primary application for the .align directive is to align the SPC so that the 
code that follows .align starts on a cache boundary. The TMS34010 in¬ 
struction cache is composed of 256 bytes of RAM, organized into four cache 
segments. Each cache segment is organized into eight blocks of four 16-bit 
instruction words, or 32 16-bit instruction words total. Figure 5-7 shows 
cache segment organization. 



WfflM 

EBB 


Each subsegment can 
store 4 16-bit 
instruction words 


Figure 5-7. Cache Segment Organization 
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Assembler Directives - Directives that Format the Output Listing 


5.5 Directives that Format the Output Listing 

Seven directives format the listing file: 

• The .length directive controls the page length of the listing file. You 
can use this directive to adjust listings for various output devices. 

• The .width directive controls the page width of the listing file. You can 
use this directive to adjust listings for various output devices. 

• The .list and .nolist directives turn the output listing on and off. By 
default, the assembler acts as if it has assembled a .list directive. You 
can use the .nolist directive to stop the assembler from printing selected 
source statements in the listing file. Use the .list directive to turn the 
listing back on. These directives can be nested. 

• The .mlist and mnolist directives allow and inhibit macro expansion 
listings. These directives can be nested. 

• The .option directive controls several features in the listing file. This 
directive has several operands: 

B Limits the listing of .byte directives to 1 line. 

D Limits the listing of .word directives to 1 line. 

F Resets the B, D, L, M, and T directives. 

L Limits the listing of .long and .int directives to 1 line. 

M Turns off macro expansions. 

T Limits the listing of .string directives to 1 line. 

X Produces a cross-reference listing of symbols. (You can also ob¬ 
tain a cross-reference listing by invoking the assembler with the -x 
option.) 

• The .page directive causes a page eject in the output listing. 

• The .title directive supplies a title that the assembler will print on the 
first line of each page. 
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Assembler Directives - Conditional Assembly Directives 


5.6 Conditional Assembly Directives 

Three directives allow you to assemble conditional blocks of code: 

• The .if directive marks the beginning of a conditional block. The .if di¬ 
rective has one parameter, which is an expression: 

- If this expression evaluates to true (a nonzero value), then the as¬ 
sembler assembles the code that follows it (up to an .else or .en- 
dif). 

- If this expression evaluates to false (0), then the assembler as¬ 
sembles code that follows an .else (if present) or an .endif (if no 
.else is present). 

• The .else directive indicates a block of code that the assembler assem¬ 
bles if the if-expression is false (0). This directive is optional in the 
conditional block; if an expression is 0 and there is no .else statement, 
then the assembler continues with the code that follows the .endif. 

• The .endif directive terminates a conditional block. 

The assembler supports several relational operators that are especially useful 

for conditional expressions; see Section 4.8.4 (page 4-14) for more informa¬ 
tion about relational operators. 

Figure 5-8 shows an example of conditional assembly. 


0004 


0001 

syml 

0005 


0002 

sym2 

0006 


0003 

sym3 

0007 

0008 


0004 

sym4 

0009 

0010 

00000000 

01 

If_l 

0011 

0012 

0013 

0014 



If—2 

0015 

0016 

0017 

0018 

0019 

00000008 

01 

If—3 

0020 

0021 

0022 

0023 

00000010 

01 



. set 

1 




. set 

2 




. set 

3 




. set 

4 




.if 

syml 

< 

sym4 


.byte 

syml 




. else 





.byte 

sym4 




. endif 





. if 

syml 

+ 

sym2 : 

= sym4 

.byte 

sym4 




. else 





.byte 

sym4 

- 

(syml 

+ sym2) 

. endif 





.if 

syml 

<> 

sym4 

- sym2 

.byte 

syml 




. else 





.byte 

sym4 

- 

sym2 


. endif 






Figure 5-8. An Example of Conditional Assembly 
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Assembler Directives - Directives that Reference Other Files 


5.7 Directives that Reference Other Files 

These directives supply information for or about other files: 

• The .copy and .include directives tell the assembler to read source 
statements from another file. When the assembler is done reading the 
source statements in the copy/include file, it resumes reading source 
statements from the current file. The statements read from a copied file 
are printed in the listing file; the statements read from an included file 
are not printed in the listing file. 

• The .global directive declares a symbol to be external so that it is avail¬ 
able to other modules at link time. The .global directive does double 
duty, acting as a .def for defined symbols and as a .ref for undefined 
symbols. Note that the linker will resolve an undefined global symbol 
only if it is used in the program. 

• The .def directive identifies a symbol that is defined in the current mo¬ 
dule and can be used by other modules. The assembler puts the symbol 
in the symbol table. 

• The .ref directive identifies a symbol that is used in the current module 
and defined in another module. The assembler marks the symbol as an 
undefined external symbol and puts it in the object symbol table so the 
linker can resolve its definition. 

• The .mlib directive supplies the assembler with the name of an archive 
library that contains macro definitions. When the assembler encounters 
a macro that is not defined in the current module, it searches for it in the 
specified macro library. 
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Assembler Directives - Directives Reference 


5.8 Directives Reference 

The remainder of this chapter is a reference. Generally, the directives are or¬ 
ganized alphabetically, one directive per page; however, related directives 
(such as .if/.else/.endif) are presented together on one page. Here's an al¬ 
phabetical table of contents for the directives reference: 

Directive Page 

.align.5-15 

.bes .5-39 

.bss .5-16 

.byte.5-17 

.copy.5-18 

.data.5-20 

.def.5-28 

.double .5-21 

.else . 5-30 

.end.5-22 

.endif .5-30 

.even . 5-23 

.field. 5-25 

.float .5-27 

.global .5-28 

.if.5-30 

.include .5-18 

.int. 5-33 

.length .5-31 

.list .5-32 

.long .5-33 

.mlib.5-34 

.mlist.5-36 

.mnolist .5-36 

.nolist.5-32 

.option .5-37 

.page.5-38 

.ref.5-28 

.sect . 5-39 

.set .....5-40 

.space . 5-41 

.string .5-42 

.text. 5-43 

.title.5-44 

.usect .5-45 

.width .5-31 

.word .5-47 
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Align SPC on a 32-Word Boundary 


.align 


Syntax .align 

Description The .align directive aligns the section program counter on the next 32-word 
boundary. This ensures that subsequent code can start on a cache bound¬ 
ary. If the space between the current SPC and the new (aligned) SPC is 
three words or less, the assembler fills this space with NOPs; otherwise, it 
inserts a jump instruction to the new SPC. 

Using the .align directive has two effects: 

• The assembler aligns the SPC on a 32-word (cache) boundary within 
the current section. 

• The assembler sets a flag that forces the linker to align the section so 
that individual alignments remain intact when a section is loaded into 
memory. 

Example This example aligns the SPC on the next 32-word boundary. This assures 

that the clr_array loop can start on a cache boundary. 


0003 

0004 

0005 

0006 

0007 

0008 

0009 00000000 
0010 
0011 
0012 
0013 
0014 
0015 


******************************************** 

* Reserve space for a 100-element array. * 

* The symbol array—start points to the * 

* first address in the array. * 

******************************************** 

0640 array—size: .set 640h 

array—start: .bss temparray, array—size, 16 

******************************************** 

* Initialize the array with 0s; the loop * 

* is aligned so it can start on a cache * 

* boundary. * 

******************************************** 


0016 00000000 0550 

0017 00000010 5621 

0018 00000020 09E0 

00000030 00000000+ 

0019 00000050 09C2 

00000060 0640 

0020 00000200 

0021 00000200 9020 clr_array: 

0022 00000210 3C42 


SETF 

16, 0 ; FS0 = 0 , 

, FE0=0 

CLR 

A1 


MOVI 

array—start, A0 


MOV I 

array—size, A2 


.align 

; Align 

the loop 

MOVE 

Al,*A0+ 


DSJS 

A2, clr_array 
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.bss 


Reserve Space in the .bss Section 


Syntax .bss symbol, size in bits [, word alignment flag] 

Description The .bss directive reserves space in the .bss section for variables. This di¬ 
rective is usually used to allocate variables in RAM. 

• The symbol is a required parameter. It defines a symbol that points 
to the first location reserved by the directive. The symbol name cor¬ 
responds to the name of the variable that you're reserving space for. 

• The size is a a required parameter; it must be an absolute expression. 
The assembler allocates size bits in the .bss section. There is no de¬ 
fault size. 

• The word alignment flag is an optional parameter. If you specify a 
nonzero value for the alignment flag, the assembler will align the re¬ 
served space on a 16-bit (word) boundary within .bss. If you specify 
a value of zero for the alignment flag, the assembler will not align the 
reserved space; this is also the default if no alignment flag is specified. 

Other sections directives (.text, .data, and .sect) end the current section and 
begin assembling into another section. The .bss directive, however, does 
not affect the current section. The assembler assembles the .bss directive 
and then resumes assembling code into the current section. For more in¬ 
formation about COFF sections, see Section 3. 

Example This example uses the .bss directive to allocate space in .bss for two vari¬ 

ables, stack—size and C—array. 


00000000 


** Begin assembling into .data ** 

****************************************************** 


stack—size: 


2048 * 16 


00000000 


****************************************************** 
** Reserve 2k words in .bss for a software stack; ** 
** align this space on a word boundary. The symbol ** 
** stack points to the stack's first address. ** 

****************************************************** 

.bss stack, stack—size, 1 


000E 

00000000 09EE 
00000010 00000000 + 


****************************************************** 
** Still in .data. Set up register A14 as the soft- ** 
** ware stack pointer? the symbol STK refers to A14.** 
****************************************************** 

STK: .set A14 

MOVI stack, STK 


****************************************************** 
** Reserve space in .bss for a 100-element array. ** 
** Each element has a size of 2 bits; the array is ** 
** not aligned on a word boundary. ** 

****************************************************** 

.bss C_array, 100 * 2, 0 


** Still in .data. Declare external .bss symbols. ** 
.global stack, C—array 
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Initialize Byte 


.byte 


Syntax 

Description 


Example 


.byte valuei [, value n ] 

The .byte directive places one or more 8-bit values into consecutive bytes 
of the current section. A value can be either: 

• An expression which the assembler evaluates and treats as an 8-bit 
signed number. 

• A character string enclosed in double quotes. Each character repres¬ 
ents a separate value. 

You can use as many values as fit on a single line. If you use a label, it 
points to the location at which the assembler places the first byte. 


Note: 

The first byte is always aligned on an 8-bit boundary. 


This example places several 8-bit values into consecutive bytes in memory. 
The label strx has the value 20h, which is the location of the first initialized 
byte. 


0001 00000000 
0002 00000020 
00000028 
00000030 
0003 00000038 
00000040 

00000048 
00000050 
0004 00000058 
0005 00000060 
0006 00000068 


32 strx: 

FF 

42 

61 

62 

63 

88 

61 

62 

63 


.space 020h 
.byte 32h, 


. byte 


byte 

'a 

byte 

'b 

byte 

1 c 


-1, 'A' + 1 

"abc", 1 D ’ *2 
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.copy/, include 


Copy Source File 


Syntax 


Description 


.copy ["]filename["] 

.include ["]filename["] 

(The quote marks surrounding the filename are optional.) 

The .copy and .include directives tell the assembler to read source state¬ 
ments from another file. The assembler: 

1) Stops assembling statements in the main source file, 

2) Assembles the statements in the copied/included file, and 

3) Resumes assembling statements in the main source file, starting with 
the statement that follows the .copy or .include directive. 

The filename is a required parameter that names a source file; the filename 
may be enclosed in double quotes. The filename must follow operating 
system conventions. You can specify a full pathname (for example, .copy 
c:\gsp\filel. asm). If you do not specify a full pathname, the assembler 
searches for the file in: 

1) The directory that contains the current source file. 

2) Any directories named with the -i assembler option. 

3) Any directories specified by the environment variable A—DIR. 

For more information about the -i option and the environment variable, see 
Section 4.3, Specifying Alternate Directories for Assembler Input, on page 
4-4. 


The statements that are assembled from a copy file are printed in the as¬ 
sembly listing. The statements that are assembled from an include file are 
not printed in the assembly listing, regardless of the number of .nolist/.list 
directives that are assembled. 

The .copy and .include directives can be nested within a file being copied 
or included. The assembler limits this type of nesting to eight levels; the 
host operating system may set additional restrictions. The assembler pre¬ 
cedes the line numbers of copied files with a letter code to identify the level 
of copying. An A indicates the first copied file, B indicates a second copied 
file, etc. 
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Copy Source File 


copy/, include 


Example 1 This example uses the .copy directive to assemble source statements from 
other files, then resumes assembling into the current file. 


copy.asm 
(source file) 

byte2.asm 
(first copy file) 

word2.asm 
(second copy file) 

. space 030h 

** In byte2.asm 

** In word2.asm 

.copy "byte2.asm" 

.byte 32, 64 

.word OABCDh, 56 


.copy "word2.asm" 


** Back in original file 

** Back in byte2.asm 


.string "done” 

.byte 67h 



Listing 

file: 


0001 

0002 

A0001 

00000000 


A0002 

00000030 

20 

A0003 

B0001 

00000038 

40 

B0002 

00000040 

ABCD 

A0004 

00000050 

0038 

A0005 

0003 

0004 

00000060 

67 

0005 

00000068 

64 


00000070 

6F 


00000078 

6E 


00000080 

65 


.space 030h 
.copy "byte2.asm" 
** In byte2.asm 

.byte 32, 64 

.copy "word2.asm" 
** In word2.asm 

.word OABCDh, 56 

** Back in byte2.asm 
.byte 67h 

** Back in original file 
.string "done" 


Example 2 This example is analogous to the first example; however, it uses the .include 
directive to assemble source statements from other files. Compare the list¬ 
ing files of these examples. 


copy2.asm 
(source file) 

byte3.asm 
(first include file) 

word3.asm 
(second include file) 

.space 030h 

** In byte3.asm 

** In word3.asm 

.include "byte3.asm" 

.byte 32, 64 

.include "word3.asm" 

.word OABCDh, 56 

** Back in original file 

** Back in byte3.asm 


.string "done" 

.byte 67h 



Listing file: 


0001 

0002 

0003 

0004 

00000000 


0005 

00000068 

64 


00000070 

6F 


00000078 

6E 


00000080 

65 


.space 030h 
.include "byte3.asm" 

Back in original file 
.string "done" 
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data 


Assemble into .data Section 


Syntax .data 


Description The .data directive tells the assembler to begin assembling source code into 
the .data section; .data becomes the current section. The .data section is 
normally used to contain tables of data or preinitialized variables. 

Section 3 provides a detailed explanation about COFF sections. 

Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the 
.text section unless an explicit section control directive is specified. 


Example This examples assembles code into the .data and .text sections. 

0001 



******************************************* 

0002 



* * 

Begin assembling into .data ** 

0003 



******************************************* 

0004 

00000000 



. data 

; ASCII table 

0005 

00000000 

0000 

asc—null 

: .word 

OOh 

0006 

00000010 

0001 

asc_soh: 

.word 

Olh 

0007 

00000020 

0002 

asc-stx: 

.word 

02h 

0008 

00000030 

0003 

asc—etx: 

.word 

03h 

0009 

00000040 

0004 

asc—eot: 

. word 

04h 

0010 

00000050 

0005 

asc—enq: 

. word 

05h 

0011 

00000060 

0006 

asc—ack: 

.word 

06h 

0012 

00000070 

0007 

asc_bel: 

.word 

07h 

0013 

00000080 

0008 

asc—bs: 

. word 

08h 

0014 




.global 

asc—null, asc_soh, asc-stx 

0015 




.global 

asc—etx, asc—eot, asc—enq 

0016 




.global 

asc—ack, asc—bel, asc—bt 

0017 






0018 



******************************************* 

0019 



* * 

Begin assembling into .text ** 

0020 



******************************************* 

0021 

00000000 



. text 


0022 

00000000 

0360 


DINT 


0023 

00000010 

0550 


SETF 

16, 0 

0024 






0025 



******************************************* 

0026 



** Resume assembling into .data ** 

0027 



***************** 

************************** 

0028 

00000090 



. data 


0029 

00000090 

0041 

asc—A: 

. word 

04 lh 

0030 

000000A0 

0042 

asc_B: 

.word 

042h 

0031 

000000B0 

0043 

asc—C: 

. word 

043h 

0032 

ooooooco 

0044 

asc—D: 

. word 

044h 

0033 

000000D0 

0045 

asc—E: 

.word 

045h 

0034 

000000E0 

0046 

asc_F 

.word 

046h 

0035 




.global 

asc—A, asc—B, asc—C 

0036 




.global 

asc_D, asc—E, asc-F 
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Initialize Double-Precision Floating Point Value 


.double 


Syntax 

Description 


Example 


.double floating-point value 

The .double directive places a 64-bit double-precision representation of a 
floating-point constant into the current section. The C compiler uses the 
.double directive to initialize floating-point constants that can be manipu¬ 
lated with the C floating-point runtime support. 

The TMS34010 C Compiler User's Guide describes the representation of 
floating-point numbers. 

The floating-point value that is specified as an operand for the .double di¬ 
rective must be a floating-point constant. A floating-point constant is a 
string of decimal digits, followed by an optional decimal point, a fractional 
portion, and an exponent portion. 

The syntax for a floating-point constant is: 

[ +|-7 [nnn] [ .nnn] [ E\e [ +| - ] nnn ] 

nnn is a string of decimal digits. 

Floating-point constants may be preceded by a + or a - sign; + is the de¬ 
fault. Floating-point constants cannot be used with other arithmetic oper¬ 
ators to form an expression; for example, 3.0 + 1 is illegal. 

Here are some valid examples of the .double directive. 


0010 

000000E0 

16140148 

.double 

-1.0e2 5 


00000100 

C5384595 



0011 

00000120 

00000000 

.double 

.5 


00000140 

3FF80000 



0012 

00000160 

00000000 

.double 

3 


00000180 

401C0000 



0013 

000001A0 

00000000 

.double 

-123 


000001C0 

C06F6000 



0014 

000001E0 

F80DC337 

.double 

3.14159 


00000200 

401C90FC 



0015 

00000220 

4BEC44DE 

.double 

-0.014E-14 


00000240 

BCAE6959 



0016 

00000260 

82000000 

.double 

36el0 


00000280 

426A7A35 
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end 


End Assembly 


Syntax 

Description 

Examp/e 


.end 


The .end directive is an optional directive that terminates assembly. It 
should be the last source statement of a program. The assembler ignores 
any source statements that follow an .end directive are ignored. 

Note that this directive has the same effect as an end-of-file. 


This example shows how the .end directive terminates assembly. If any 
source statements followed the .end directive, the assembler would ignore 
them. 


0001 

00000000 


Start: 

. space 

300 

0002 


0004 

pix—size 

. set 

4 

0003 


0400 

S—pitch 

. set 

256 * pix—size 

0004 


0400 

D—pitch 

. set 

256 * pix—size 

0005 


0011 

SPTCH 

. set 

B1 

0006 


0013 

DPTCH 

. set 

B3 

0007 


C0000150 

PSIZE 

. set 

0C0000150h 

0008 

00000130 

1880 


MOVK 

pix_size, AO 

0009 

00000140 

0580 


MOVE 

AO, @PSIZE 


00000150 

C0000150 




0010 

00000170 

09D1 


MOVI 

S—pitch, SPTCH 


00000180 

0400 



0011 

00000190 

09D3 


MOVI 

D_pitch, DPTCH 


000001A0 

0400 



0012 




. end 
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Align SPC at Next Word Boundary 


.even 


Syntax .even 

Description The .even directive aligns the section program counter on the next word 
(16-bit) boundary. Since the TMS34010 is a bit-addressable processor, 
the SPC may not always be aligned on a word boundary. For example, 
some directives, such as .field, .byte, .bes, and .space, may initialize only 
part of the word. You can follow any of these directives with the .even di¬ 
rective; this forces the assembler to write out a partially filled word. If the 
SPC is already aligned on a word boundary, then the .even directive does 
not affect it. 

Note that there is an implied .even at the end of each section; this ensures 
that each section ends on an even word boundary. 

Example This example uses the .field, .byte, and .space directives to fill portions of 

words. Figure 5-9 (page 5-24) shows how .even aligns the SPC. 


0001 

0002 

0003 

0004 00000000 

0005 

0006 

0007 

0008 

0009 00000006 
0010 
0011 
0012 
0013 
0014 
0015 

0016 00000010 

0017 

0018 

0019 

0020 

0021 

0022 00000010 

0023 00000020 

0024 

0025 

0026 

0027 

0028 

0029 

0030 00000020 
0031 00000040 


* Initialize a 6-bit field * 

0008 .field 08h, 6 


* Initialize a 5-bit field * 
.field OFh, 5 


********************************** 

* The remaining bits in the word * 

* are filled with 0s and the SPC * 

* is aligned on the next word * 

********************************** 

. even 


********************************** 

* Initialize a byte in a word, & * 

* align the SPC at the next word * 
********************************** 

02 .byte 02h 

. even 


********************************** 

* Reserve 17 bits in memory, then* 

* align the SPC at the next word * 

* past the reserved space * 

********************************** 

.space 17 

. even 
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.even 


Align SPC at Next Word Boundary 


Word 

F__0 

0 |0 0 0 0 0|0 1 1 1 1 0 0 1 Q~ 0 ~o] 


| filled by .field 

*- SPC aligned by .even 

F__0 

1 |o 0 0 0 0 0 0 oToj~go~FoTo3 

t ' v ' 

| filled by .byte 

L SPC aligned by .even 


F 0 F 0 

2, 3 lOQOOOOQOOOOOOO p|0 " QQOl 


f v- 

| filled by .space 

*- SPC aligned by .even 

Figure 5-9. An Example of the .even Directive 
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Initialize Field 


field 


Syntax .field value [, size in bits] 

Description The .field directive places one value into a specified number of bits in me¬ 
mory. 

• The value is an expression that is evaluated and placed in the field. 
If the value is relocatable, size must be 32. 

• The size is optional; it specifies a number from 1-32, which is the 
number of bits the field consists of. If you do not specify a size the 
assembler assumes that the size is 32 bits. If you specify a value that 
cannot fit in size bits, the assembler truncates the value and issues an 
error message. 


Note: 

The section program counter is not aligned before or after the value 
is placed in memory. 


Example This example shows how multiple-bit fields are initialized. Figure 5-10 

(page 5-26) shows how the fields are initialized. 


0001 

0002 

0003 

0004 00000000 OABC 

0005 
0006 
0007 
0008 
0009 
0010 

0011 0000000E 000A 

0012 

0013 

0014 

0015 

0016 

0017 00000013 000C 

0018 

0019 

0020 

0021 

0022 

0023 00000017 0001 

0024 
0025 
0026 
0027 
0028 

0029 0000001A 00000017' 


************************************* 

* Initialize a 14-bit field * 

************************************* 

.field OABCh, 14 

************************************* 

* Initialize a 5-bit field -- the * 

* first two bits are in one word, * 

* the next 3 bits are in another * 

************************************* 

I—F: .field OAh, 5 

************************************* 

* Initialize a 4-bit field in the * 

* same word * 

************************************* 

.field OCh, 4 

************************************* 

* Initialize a 3-bit field in the * 

* same word * 

************************************* 

x: .field Olh, 3 


************************************* 

* Initialize a 32-bit relocatable * 

* field in the next word * 

************************************* 

.field x 
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field 


Initialize Field 


DCBA9876543210 
0010101011110 0 | 

'-v- ' 

14-bit field 


12 11 10 F E 

0 1 0 1 1 o] 

5-bit field 


16151413 

iio 


4-bit field 


191817 

0 0 l[l 1 00 01 o[ 


3-bit field 


Code 

.field OABCh, 14 

.field OAh, 5 

.field OCh, 4 

.field Olh, 3 


3F 262524232221201FIE1D1C1B1A 

[0 0 0 0 0~0 0 0 0 0 0 1 7[0 0 0 0 0 0[ .field x 


V V 1 1 

32-bit relocatable field SPC aligned 

Figure 5-10. Examples of the .field Directive 
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Initialize Single-Precision Floating Point Value 


.float 


Syntax 

Description 


Example 


.float floating-point value 

The .float directive places a 32-bit, single-precision representation of a 
floating-point constant into the current section. The C compiler uses the 
.float directive to initialize floating-point constants that can be manipulated 
with the C floating-point runtime support. 

The TMS34010 C Compiler User's Guide describes the internal represen¬ 
tation of floating-point numbers. 

The floating-point value that is specified as an operand for the .float direc¬ 
tive must be a floating-point constant. A floating-point constant is a string 
of decimal digits, followed by an optional decimal point, a fractional por¬ 
tion, and an exponent portion. 

The syntax for a floating-point constant is: 

[ +|- 7 [nnn] [ .nnn] [ E\e [ +|- ] nnn ] 

nnn is a string of decimal digits. 

Floating-point constants may be preceded by a + or a - sign; + is the de¬ 
fault. Floating-point constants cannot be used with other arithmetic oper¬ 
ators to form an expression; for example, 3.0 + 1 is illegal. 

Here are some valid examples of the .float directive. 


0001 

00000000 

E9C22CA9 

.float 

-1.0e25 

0002 

00000020 

3FC00000 

.float 

.5 

0003 

00000040 

40E00000 

.float 

3 

0004 

00000060 

C37B0000 

.float 

-123 

0005 

00000080 

40E487E8 

.float 

3.14159 

0006 

000000A0 

A5734ACA 

.float 

-0.014E-14 

0007 

ooooooco 

5353D1AC 

.float 

36el0 
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.global/, ref/, def 


Identify Global Symbols 


Syntax 


Description 


Example 


.global symbol / [, symbo/ n ] 

.def symbolj [, symbol n ] 

.ref symbol j symbol n ] 

The .global, .ref, and .def directives identify symbols that can be referenced 
externally. 

• The .def directive identifies a symbol that is defined in the current 
module and can be accessed by other files. The assembler places this 
symbol in the symbol table. 

• The .ref directive identifies a symbol that is defined in another module 
and used in the current module. The linker resolves this symbol's 
definition at link time. 

• The .global directive acts as a .ref or a .def, as needed. 

A global symbol is defined in the same manner as any other symbol; that is, 
it appears as a label or is defined by the .set, .bss, or .usect directive. As 
with all symbols, if a global symbol is defined more than once, the linker 
will issue a multiple-definition error. Note that .ref always creates an entry 
for a symbol, whether the module uses the symbol or not; .global, however, 
only creates a symbol table entry if the module actually uses the symbol. 

There are two main reasons for declaring symbols as global: 

1) If the symbol is not defined in the current source module (this in¬ 
cludes copy/include files and macro libraries), then the .global or .ref 
directive tells the assembler that the symbol is defined in an external 
module. This prevents the assembler from issuing an unresolved ref¬ 
erence error. At link time, the linker will look for the symbol's defi¬ 
nition in other modules. 

2) If the symbol is defined in the current module , then the .global or .def 
directive declares that the symbol and its definition can be used ex¬ 
ternally in other modules. These types of references will be resolved 
at link time. 

This example uses four files: 

• filel. 1st and file3.1st are equivalent. Both files define the 

symbol Init and make it available to other modules; both files use the 
external symbols x, y, and z. filel. 1st uses the .global directive 

to identify these global symbols; file3.1st uses .ref and .def to 
identify the symbols. 

• file2.1st and file4.1st are equivalent. Both files define the 
symbols x, y, and z, and make them available to other modules; both 
files use the external symbol init. file2.1st uses the .global di¬ 
rective to identify these global symbols; f ile4.1st uses .ref and .def 
to identify the symbols. 
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Identify Global Symbols 


global/.ref/.def 


filel.lst: 


0001 


* 

Global symbol 

defined in this file 

0002 



.global 

Init 

0003 


* 

Global symbols 

defined in another file 

0004 



.global 

x, y, z 

0005 00000000 


Init: 


0006 00000000 

09E0 


MOVI 

x, A0 

00000010 

00000000! 




0007 


J 



0008 


; 

. 


0009 


} 



0010 



. end 


file2.lst: 





0001 


* 

Global symbols 

defined in this file 

0002 



.global 

x, y, z 

0003 


* 

Global symbol 

defined in another file 

0004 



.global 

Init 

0005 

0001 

X 

. set 

1 

0006 

0002 

y 

. set 

2 

0007 

0003 

z 

. set 

3 

0008 00000000 

0000 


. word 

Init 

0009 


; 



0010 


; 

. 


0011 


/ 



0012 



. end 


f ile3.1st: 





0001 


* 

Global symbol 

defined in this file 

0002 



. def 

Init 

0003 


* 

Global symbols 

defined in another file 

0004 



. ref 

x, y, z 

0005 00000000 


Init: 


0006 00000000 

09E0 


MOVI 

x, A0 

00000010 

00000000! 




0007 


/ 

. 


0008 


; 

. 


0009 





0010 



. end 


f i Ie4.1st: 





0001 


* 

Global symbols 

defined in this file 

0002 



. def 

x, y, z 

0003 


* 

Global symbol 

defined in another file 

0004 



.ref 

Init 

0005 

0001 

X: 

. set 

1 

0006 

0002 

y: 

. set 

2 

0007 

0003 

z : 

. set 

3 

0008 00000000 

0000 


. word 

Init 

0009 


} 

. 


0010 


} 

. 


0011 


■ 

. 


0012 



. end 
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.if/.else/.endif 


Assemble Conditional Blocks 


Syntax .if well-defined expression 

code to assemble if expression is true (& 0) 

.else 

code to assemble if expression is false (= 0) 

.endif 

Description Three directives provide conditional assembly: 

• The .if directive identifies the beginning of a conditional block. Ex¬ 
pression is a required parameter. 

- If the expression evaluates to true (a nonzero value), then the 
assembler will assemble the code that follows it (up to an .else 
or .endif). 

- If this expression evaluates to false (0), then the assembler will 
assemble code that follows an .else (if present) or an .endif (if 
no .else is present). 

• The .else directive identifies a block of code that the assembler will 
assemble if the if-expression is false (0). This directive is optional in 
the conditional block; if an expression is 0 and there is no .else state¬ 
ment, then the assembler will continue with the code that follows the 
.endif. 

• The .endif directive terminates a conditional block. 

Example Here are some examples of conditional assembly: 


0001 


0001 

syml 

. set 

1 




0002 


0002 

sym2 

. set 

2 




0003 


0003 

sym3 

. set 

3 




0004 


0004 

sym4 

. set 

4 




0005 









0006 



If—4 : 

.if 

sym4 

= 

sym2 * 

sym2 

0007 

00000000 

04 


.byte 

sym4 



; Equal values 

0008 




. else 





0009 




.byte 

sym2 

* 

sym2 

; Unequal values 

0010 




.endif 





0011 









0012 



If—5 : 

.if 

syml 

<= 10 


0013 

00000008 

01 


. byte 

syml 



; Less than/equal 

0014 




.endif 





0015 









0016 



If—6: 

.if 

sym3 

* 

sym2 ! 

= sym4 + sym2 

0017 




.byte 

sym4 

+ 

sym2 

; Unequal values 

0018 




. else 





0019 

00000010 

06 


.byte 

sym3 

* 

sym2 

; Equal values 

0020 




.endif 
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Set Listing Page Size 


.length/.width 


Syntax 


Description 


Examp/e 


.length page length 
.width page width 


The .length directive sets the page length of the output listing file. It affects 
the current page and following pages; you can reset the page length with 
another .length directive. 

• Default length: 60 lines 

• Minimum length: 1 line 

• Maximum length: 32,767 lines 

The .width directive sets the page width of the output listing file. It affects 
the next line assembled and following lines; you can reset the page width 
with another .width directive. 

• Default width: 80 characters 

• Minimum width: 80 characters 

• Maximum width: 200 characters 

Note that the width refers to a full line in a listing file; the line counter value, 
SPC value, and object code are counted as part of the width of a line. 
Comments and other portions of a source statement that extend beyond the 
page width are truncated in the listing. 

The assembler does not list the .length and .width directives. 


This example shows source statements that change the page length and 
width. 

************************ 

* * 

Page length = 65 lines * * 

Page width = 85 characters * * 

* * 

************************ 

.length 65 

.width 85 



***** 


******* 


*********** 


* * * 


* 


* * 


* * 


Page length = 55 lines 
Page width = 100 characters 


.length 55 

.width 100 
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.list/.nolist 


Start/Stop Source Listing 


Syntax 


Description 


Example 


.nolist 

.list 

The .nolist directive suppresses the source listing output until a .list direc¬ 
tive is encountered. The .list directive tells the assembler to resume printing 
the source listing after it has been stopped by a .nolist directive. By default, 
the assembler acts as if a .list directive has been specified. The .nolist di¬ 
rective can be used to reduce assembly time and the size of the source list¬ 
ing; it is frequently used in macro definitions to inhibit the listing of the 
macro expansion. 

The assembler does not print the .list or .nolist directives, or the directives 
that appear after a .nolist directive; however, it continues to increment the 
line counter. You can nest the .list/.nolist directives; each .nolist needs a 
matching .list to restore the listing. At the beginning of an assembly, the 
assembler acts as if it has assembled a .list directive. 


Note: 

If you don't request a listing file when you invoke the assembler, the 
assembler ignores the .list directive. To obtain a listing file, invoke the 
assembler with the -I (lowercase "L") option. 


This example uses the .copy directive to insert source statements from an¬ 
other file. The first time this directive is encountered, the assembler lists the 
copied source lines in the listing file. The second time this directive is en¬ 
countered, the assembler does not list the copied source lines because a 
.nolist directive was assembled. Note that the .nolist, the second .copy, and 
.list directives do not appear in the listing file; note also that the line counter 
is incremented even when source statements are not listed. 


Source File: 


* Back 


* Back 


. copy 

in original 
.nolist 
. copy 

in original 
. list 
.string 


copy2.asm" 
file 

”copy2.asm 1 
file 

’’Done” 


Listing File: 


0001 



. copy 

”copy2.asm’ 

A0001 



* In copy2.asm 

(copy file) 

A0002 

00000000 

AABBCCDD 

. long 

OAABBCCDDh 

0002 



* Back in original file 

0007 

00000040 

44 

.string 

"Done” 


00000048 

6F 



00000050 

6E 




00000058 

65 
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Initialize 32-Bit Integer 


.long/.int 


Syntax 


Description 


Example 1 


Example 2 


.long valuei [, value n ] 

.int value / [, value n ] 

The .int and the .long directives are equivalent. They place one or more 
values into consecutive 32-bit fields in the current section. The operand 
field contains one or more values separated by commas. A value can be 
either: 

• An expression which the assembler evaluates and treats as a 32-bit 
signed number. 

• A character string enclosed in double quotes. Each character repre¬ 
sents a separate value. 

You can use up to 100 values, but the total line length cannot exceed 200 
characters. 

This example uses the .long directive to initialize several 32-bit fields. The 
symbol Datl points to the first reserved word. 

0001 00000000 FFFFABCD Datl: .long OFFFFABCDh, ’A’ + lOOh 
00000020 00000141 

0002 00000040 00000000' .long Datl, "long" 

00000060 0000006C 
00000080 0000006F 
000000A0 0000006E 
000000C0 00000067 

This example uses the .int directive to initialize several 32-bit fields. The 
symbol XI points to the first reserved word. Notice the difference between 
the character constant 'Inst' and the character string "Inst". 


0001 

00000000 

XI: 

.bss 

0002 

00000200 

00000C80 

. int 


00000220 

00000000+ 



00000240 

00004242 



00000260 

00000000+ 


0003 

00000280 

74736E49 

. int 


000002A0 

00000049 



000002C0 

0000006E 



000002E0 

00000073 



00000300 

00000074 



page, 128, 16 
3200,page,l+'AB',X1 


'Inst', "Inst” 
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.mlib 


Define Macro Library 


Syntax 


Description 


Example 


5-34 


.mlib ["]filename["] 

(The quote marks surrounding the filename are optional.) 

The .mlib directive provides the assembler with the name of a macro library. 
A macro library is a collection of files that contain macro definitions. These 
files are bound into a single file (called an archive) by the archiver. Each 
member of a macro library may contain one macro definition that corre¬ 
sponds to the name of the file. Note that: 

• Macro library members must be source files (not object files). 

• The filename of a macro library member must be the same as the ma¬ 
cro name and its extension must be .asm. 

The filename must follow operating system conventions; it may be enclosed 
in double quotes. You can specify a full pathname (for example, .mlib 
e:\gsp\macs.lib). If you do not specify a full pathname, the assembler 
searches for the file in: 

1) The directory that contains the current source file. 

2) Any directories named with the -i assembler option. 

3) Any directories specified by the environment variable A—DIR. 

For more information about the -i option and the environment variable, see 
Section 4.3, Specifying Alternate Directories for Assembler Input, on page 
4-4. 

When the assembler encounters an .mlib directive, it opens the library and 
creates a table of its contents. The assembler enters the names of the indi¬ 
vidual library members into the opcode table as library entries; this redefines 
any existing opcodes or macros that have the same name. If one of these 
macros is called, the assembler extracts the entry from the library and loads 
it into the macro table. The assembler expands the library entry in the same 
manner as other macros, but it does not place the source code into the 
listing. Only macros that are actually called from the library are extracted, 
and they are only extracted once. 

This example creates a macro library that defines two macros, incl and 
decl. The file incl.asm contains the definition of incl, and decl.asm 
contains the definition of decl. 


inc—aO—8.asm 

* Macro for incrementing 

* AO by 8 
inc-aO-8 $MACRO 

ADDI 8, AO 
$ENDM 


dec—aO—8. asm 


* Macro for decrementing 

* AO by 8 

dec—a0~8 $MACRO 

SUBI 8, AO 
$ENDM 


Use the archiver to create a macro library: 
gspar -a mac inc—aO—8. asm dec—aO—8. asm 




Define Macro Library 


mlib 


Now you can use the .mlib directive to reference the macro library and de¬ 
fine the inc_a0_8 . asm and dec_a0_8 . asm macros: 


0002 

00000000 


.mlib 

"mac.lib" 

0003 

00000000 

09C0 

MOVI 

9, AO 


00000010 

0009 



0004 

00000020 


inc—AO—8 


0001 

00000020 

0B00 

ADD I 

8, AO 


00000030 

0008 



0005 

00000040 


dec-A0_8 


0001 

00000040 

OBEO 

SUBI 

o 

< 

CO 


00000050 

FFF7 
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.mlist/.mnolist 


Start/Stop Macro Expansion Listing 


Syntax 


Description 


Example 


.mlist 

.mnolist 

Two directives provide you with the ability to control the listing of macro 
expansions in the listing file: 

• The .mlist directive allows macro expansions in the listing file. 

• The .mnolist directive inhibits macro expansions in the listing file. 

By default, all macro expansions are listed. The line counter restarts 
counting at 1 during a macro expansion; it resumes counting from its pre¬ 
vious value when the macro expansion is complete. Unlisted macro ex¬ 
pansion lines do not affect the line counter. Note that you can nest the 
.mlist and .mnolist directives. 

This example defines a macro named clr_a that clears several registers in 
general-purpose register file A. The first time the macro is called, the macro 
expansion is listed (by default). The second time the macro is called, the 
macro expansion is not listed because a .mnolist directive was assembled. 
The third time the macro is called, the macro expansion is again listed be¬ 
cause a .mlist directive was assembled. 


0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 00000000 
0001 00000000 
0002 00000010 
0003 00000020 
0004 00000030 
0009 000000F0 
0010 000000F0 
0011 000001E0 
0012 000001E0 
0001 000001E0 
0002 000001F0 
0003 00000200 
0004 00000210 


clr_a 


5600 

5621 

5642 

5663 


5600 

5621 

5642 

5663 


$MACRO 


CLR 

AO 

CLR 

A1 

CLR 

A2 

CLR 

A3 

$ENDM 


clr—a 


CLR 

AO 

CLR 

A1 

CLR 

A2 

CLR 

A3 

.mnolist 


clr_a 


.mlist 


clr_a 


CLR 

AO 

CLR 

A1 

CLR 

A2 

CLR 

A3 
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Select Listing Options 


.option 


Syntax 


Description 


Example 


0001 

0002 

0003 

0004 

0005 

0006 00000000 

0007 00000000 

0008 00000020 

0009 00000060 

0010 00000080 

0011 000000E0 

0012 

0013 

0014 

0015 

0016 00000148 
0017 00000148 
00000150 
00000158 
0018 00000160 
00000180 
0019 000001A0 
000001B0 
0020 000001C0 
000001E0 
00000200 
0021 00000220 
00000228 
00000230 
00000238 
00000240 
00000248 
00000250 
00000258 
00000260 
00000268 
00000270 
00000278 
00000280 


.option option list 

The .option directive selects several options for the assembler output listing. 
The option list is a list of options separated by commas; each option selects 
a listing feature. Valid options include: 

B Limit the listing of .byte directives to one line. 

D Limit the listing of .word directives to one line. 

F Reset the B, D, L, M, and T options. 

L Limit the listing of .long directives to one line. 

M Turn of macro expansions in the listing. 

T Limit the listing of .string directives to one line. 

X Produce a symbol cross-reference listing. 

This example limits the listings of the .byte, .word, .long, .int, and .string 
directives to one line each. 





* Limit 

the listing 

of .byte, .word, .int, * 


* .long 

and .string directives to 1 line * 


* each 


* 


********************************************** 



.option 

B, D, L, T 

BD 

byte: 

.byte 

-'C', OBOh, 5 

AABBCCDD 

long: 

. long 

OAABBCCDDh, 536 + 'A' 

15AA 

word: 

.word 

5546, 78h 

00000555 

int: 

. int 

010101010101b, 356q, 85 
”1/0 Registers" 

49 

string: 

. string 


********************************************** 


* 

Reset the 

listing options * 


********************************************** 



.option 

F 

BD 


.byte 

-’C’, OBOh, 5 

BO 




05 




AABBCCDD 

00000259 


. long 

OAABBCCDDh, 536 + ’A’ 

15AA 

0078 


.word 

5546, 78h 

00000555 

000000EE 

00000055 


. int 

010101010101b, 356q, 85 

49 


. string 

"I/O Registers" 

2F 





4F 

20 

52 

65 

67 

69 

73 

74 
65 

72 

73 
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.page 


Eject Page in Listing 


Syntax .page 

Description The .page directive produces a page eject in the listing file. The .page di¬ 
rective is not printed in the source listing, but the line counter is incre¬ 
mented. Using the .page directive to divide the source listing into logical 
divisions improves program readability. 

Example This example causes the assembler to begin new pages in the source listing. 

Source file: 

.title ****** .page directive example *****" 


.page 


• page 


Listing file: 

GSP COFF Assembler, Version 1.30, 87.250 
(c) Copyright 1985, 1987, Texas Instruments Inc. 

***** .page directive example ***** 


0002 

0003 

0004 

GSP COFF Assembler, 
(c) Copyright 1985, 


Version 1.30, 87.250 

1987, Texas Instruments Inc. 


* * * * * 


.page directive example ***** 


0006 
0007 
0008 

GSP COFF Assembler, Version 1.30, 87.250 
(c) Copyright 1985, 1987, Texas Instruments Inc. 


***** .page directive example ***** 


0010 

0011 

0012 


No Errors, No Warnings 


Tue Sep 1 08:51:08 1987 
PAGE 1 

Tue Sep 1 08:51:08 1987 
PAGE 2 

Tue Sep 1 08:51:08 1987 
PAGE 3 
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Assemble into Named Section 


sect 


Syntax .sect "section name" 

Description The .sect directive defines a named section that can be used like the default 
.text and .data sections. The .sect directive begins assembling source code 
into the named section. 

The section name identifies a section that the assembler assembles code 
into. The name is significant to 8 characters and must be enclosed in dou¬ 
ble quotes. 

Section 3, Introduction to Common Object File Format, provides additional 
information about named sections. 

Example This example defines two named sections, init_grph and s_stk_l, and 

assembles code into them. 


0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 

0015 

0016 

0017 

0018 

0019 

0020 

0021 

0022 

0023 

0024 

0025 

0026 

0027 

0028 

0029 

0030 

0031 

0032 

0033 

0034 

0035 

0036 

0037 

0038 

0039 

0040 

0041 


4000 stkl—size: 


0011 

0130 


SPTCH 

CONVSP 


.set 1024 * 16 

.global stkl—size 
.set B1 

.set 0C00000130h 


00000000 

00000000 

00000010 


0550 

1911 


* Begin assembling into a named section init—grph. * 
**************************************************** 


sect 

SETF 

MOVK 


" init—grph" 
16, 0, 0 
8, SPTCH 


00000000 

00004000 


**************************************************** 

* Stop assembling into init_grph and begin assem- * 

* bling into the named section s_stk_1. This sec- * 

* tion reserves stkl—size bits; stkl—strt points * 

* to the beginning of the space, and stkl—end * 

* points to the end of the space. * 

**************************************************** 

stkl—strt: .sect "s_stk_1" 

stkl—end: .bes stkl—size 


00000000 


00000000 

00000010 


000E 


09EE 

00000000 + 


**************************************************** 

* Stop assembling into s_stk—1 and begin assem- * 

* bling into .data. Equate STK—PI with register * 

* A14; STK—PI points to the beginning of the sec- * 

* tion s—stk—1. * 

**************************************************** 

. data 

STK—PI: .set A14 

.global STK—PI 

MOVI stkl—strt, STK—PI 


00000020 

00000020 

00000030 

00000040 


6A30 

0590 

00000130 


**************************************************** 

* Stop assembling into .data and begin assembling * 

* into init—grph. * 

**************************************************** 

.sect "init—grph" 

LMO SPTCH, B0 

MOVE B0, @CONVSP, 0 
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.set 


Define Assembly-Time Constant 


Syntax symbol .set value 


Description The .set directive equates a value to a symbol. The symbol can then be used 
in place of a value in assembly source. This allows you to assign mean¬ 
ingful names to constants and other values. 

• The symbol must appear in the label field. 

• The value must be a well-defined expression; that is, all symbols in the 
expression must have been previously defined in the current module. 
Undefined external symbols and symbols that are defined later in the 
module cannot be used in the expression. If the expression is relo¬ 
catable, the symbol to which it is assigned is also relocatable. 

The value assigned to the symbol appears in the object field of the listing. 
This value is not part of the actual object code and is not written to the 
output file. 


Example This example shows how symbols can be assigned with .set. 


0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 


0000 

11111111 

22222222 

0008 


***************************************** 

* Assign values to symbol names (define * 

* assembly-time constants). * 

***************************************** 

BLACK ^ 

BLUE 
RED 

pix_sz 


. set 
. set 
. set 
. set 


Ollllllllh 

022222222h 

8 


***************************************** 

* Equate registers B8 and B9 with their * 

* descriptive names and put values into * 

* them. * 

***************************************** 


0015 


0018 

COLORO 

. set 

B8 

0016 


0019 

COLOR1 

. set 

B9 

0017 

00000000 

00000010 

09F8 

11111111 


MOVI 

BLUE 

0018 

00000030 

00000040 

09F9 

22222222 


MOVI 

RED, 


0019 

0020 

0021 

0022 

0023 

0024 

0025 

0026 

0027 00000060 
0028 00000070 
00000080 


C0000150 

C0000160 

1903 

0583 

C0000150 


***************************************** 

* Equate I/O register names with their * 

* memory addresses. Load the PSIZE reg- * 

* ister with a value. * 

***************************************** 


PSIZE .set 
PMASK .set 

MOVK 

MOVE 


0C0000150h 
0C0000160h 

pix—sz, A3 
A3, @PSIZE 


0029 

0030 

0031 

0032 

0033 

0034 

0035 

0036 

0037 


000000A0 000A 

00A1* 

000000B0 0B2 3 

000000C0 000000A1' 


***************************************** 

* Set symbol rel—sym to a relocatable * 

* expression and use it as a relocatable* 

* operand. * 

***************************************** 

label .word 10 

rel_sym .set label + 1 

ADDI rel—sym, A3 
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Reserve Space 


space/.bes 


Syntax .space size in bits 

.bes size in bits 

Description The .space and .bes directives reserve size number of bits in the current 
section and fill them with Os. The section program counter is realigned to 
point to the bit following the reserved space. 

When you use a label with the .space directive, it points to the first bit re¬ 
served. When you use a label with the .bes directive, it points to the last 
bit reserved. 


Note: 

The assembler performs no alignment before or after executing a .space 
directive. You can use the .even directive to align the SPC. 


Example 


This example reserves memory with the .space and .bes directives. 


0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 

0015 

0016 

0017 

0018 

0019 

0020 

0021 

0022 


0023 

0024 

0025 

0026 

0027 

0028 

0029 

0030 

0031 

0032 

0033 


00000000 

00000000 


00000010 

00000014 

00000020 


00000000 

00000000 

00000008 

00000010 

00000018 


000A 


***************************************************** 

** Begin assembling into .text. ** 

***************************************************** 

. text 
.word 10 

***************************************************** 
** Use the .space directive to reserve 12 bits in ** 
** the .text section. These bits are in the same ** 
** word whose first 4 bits were initialized by the ** 
** .field directive. The label Ll points to bit ** 
** address 14h; this is the first bit reserved. ** 
***************************************************** 


0008 

0014 


44 

61 

74 

61 


Ll: 


.field 8,4 

.space 12 


. word 


Ll 


** Begin assembling into .data. ** 

***************************************************** 

. data 

.string "Data" 


** 


** Use the .space and .bes directives to reserve 
** 22 bits in the .data section. The first 8 bits 
** reserved by .space are in the same word whose 
** first 8 bits were initialized by a preceding 
** .byte directive. The label Res—1 points to bit 
** address 28h; this is the first bit reserved by 
** - ' _ 

* * 


* * 
* * 
** 
** 
* * 
* * 
* * 


.space. The label Res—2 points to bit address 
4A; this is the last bit reserved by .bes. 


0034 

00000020 

24 


. byte 

36 

0035 

00000028 


Re s_1: 

.space 

Ollh 

0036 

0000004A 


Re s_2 : 

. bes 

Ollh 

0037 

00000050 

0028 


. word 

Res—1 

0038 

00000060 

004A 


. word 

Res_2 
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.string 


Initialize Text 


Syntax .string " string j" [, ..." string n "J 

Description The .string directive places 8-bit characters from one or more character 
strings into consecutive bytes in the current section. Each string is either: 

• An expression which the assembler evaluates and treats as a 16-bit 
signed number. 

• A character string enclosed in double quotes. Each character in a 
string represents a separate byte. 

The first character is aligned on an 8-bit boundary; the string is not padded. 


Example This example initializes bytes with 8-bit ASCII characters. 


0001 

00000000 


. data 


0002 

00000000 


. space 

1024 

0003 

00000400 

65 

. string 

"end of data" 


00000408 

6E 



00000410 

64 




00000418 

20 




00000420 

6F 




00000428 

66 




00000430 

20 




00000438 

64 




00000440 

61 




00000448 

74 




00000450 

61 



0004 

00000000 


. sect 

"strings" 

0005 

00000000 

41 strs: 

.string 

"Austin","San Antonio","Houston 


00000008 

75 




00000010 

73 




00000018 

74 




00000020 

69 




00000028 

6E 




00000030 

53 




00000038 

61 




00000040 

6E 




00000048 

20 




00000050 

41 




00000058 

6E 




00000060 

74 




00000068 

6F 




00000070 

6E 




00000078 

69 




00000080 

6F 




00000088 

48 




00000090 

6F 




00000098 

75 




000000A0 

73 




000000A8 

74 




000000B0 

6F 




000000B8 

6E 
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Assemble into .text Section 


.text 


Syntax .text 

Description The .text directive tells the assembler to begin assembling into the .text 
section, which contains executable code. The SPC is set to 0 if no code 
has been assembled into .text; if .text already contains code, the SPC is re¬ 
stored to its previous value in the section. 

Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the 
.text section unless you specify one of the other sections directives (.data 
or .sect). 

For more information about COFF sections, see Section 3. 

Example This example assembles code into the .text and .data sections. 


0001 0000 

0002 0000 

0003 

0004 

0005 

0006 00000000 

0007 00000000 0360 

0008 00000010 0550 

0009 00000020 0744 

0010 

0011 

0012 

0013 

0014 00000000 

0015 00000000 0000 

0016 00000010 0004 

0017 

0018 

0019 

0020 

0021 00000030 
0022 00000030 05C0 

00000040 00000000" 
00000060 00000000 
0023 00000080 05C0 

00000090 00000010" 
000000B0 00000000 


PSIZE .set 0C0000150 

PMASK .set 0C0000160 

************************************* 

** Begin assembling into .text ** 
************************************* 

. text 

DINT 

SETF 16, 0, 0 
SETF 4, 0, 1 

************************************* 

** Begin assembling into .data ** 
************************************* 

. data 

plmask .word 0000 

pixsz .word 4 

************************************* 

** Resume assembling into .text ** 
************************************* 

. text 

MOVE @plmask, @PMASK 


MOVE @pixsz, @PSIZE 
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.title 


Define Page Title 


Syntax .title " string " 

.title 7 string' 

(Enclose the string with single or double quotes.) 


Description The .title directive supplies a title that is printed in the heading on each 
listing page. The .title directive itself is not printed, but the line counter is 
incremented. 

The string is a quote-enclosed title of up to 65 characters. If you supply 
more than 65 characters, the assembler truncates the string and issues a 
warning. The assembler prints the title on the page that follows the direc¬ 
tive, and on subsequent pages until another .title directive is processed. 

Example This example prints the title**** Floating-Point Routines **** on 

the first listing page and **** pixel Block Transfers **** on the 
second page. 

Source file: 

.title "**** Floating-Point Routines ****" 


.page 

.title ••**** pixel Block Transfers ****" 


Listing file: 

GSP COFF Assembler, Version 1.30, 87.250 Wed Sep 9 16:50:53 1987 

(c) Copyright 1985, 1987, Texas Instruments Inc. 

**** Floating-Point Routines **** PAGE 1 

0002 ; 

0003 ; 

0004 

GSP COFF Assembler, Version 1.30, 87.250 Wed Sep 9 16:50:53 1987 

(c) Copyright 1985, 1987, Texas Instruments Inc. 

**** Pixel Block Transfers **** PAGE 2 

0006 ; 

0007 ; 

0008 ; 
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Reserve Uninitialized Space 


.usect 


Syntax 

Description 


Example 


symbol .usect "section name ", size in bits [, word alignment flag] 

The .usect directive reserves space for variables in an uninitialized, named 
section. This directive is similar to the .bss directive; both simply reserve 
space for data - their sections have no contents. However, .usect defines 
additional sections that can be placed anywhere in memory, independently 
of the .bss section. 

• The symbol points to the first location reserved by this invocation of 
the .usect directive. The symbol corresponds to the name of the var¬ 
iable that you're reserving space for. 

• The section name must be enclosed in double quotes; only the first 8 
characters are significant. This parameter names the uninitialized 
section. 

• The size is an expression that defines the number of bits that are re¬ 
served in section name. 

• The word alignment flag is an optional parameter. If you specify a 
nonzero value for the alignment flag, the assembler aligns the reserved 
space on a 16-bit (word) boundary within .bss. If you specify a value 
of zero for the alignment flag, the assembler does not align the re¬ 
served space; this is also the default if alignment flag is not specified. 

Other sections directives (.text, .data, and .sect) end the current section and 
tell the assembler to begin assembling into another section. The .usect and 
the .bss directives, however, do not affect the current section. The assem¬ 
bler assembles the .usect and the .bss directives and then resumes assem¬ 
bling into the current section. 

You can repeat the .usect directive to define more than one variable in the 
specified section. Variables which can be located contiguously in memory 
can be defined in the same section by using multiple .usect directives with 
the same section name. 

For more information about COFF sections, see Section 3. 

This example uses the .usect directive to define two uninitialized, named 
sections, pixarray and uninit—V. The symbol ar_1 points to the first 
bit reserved in the pixarray section. The symbol ar_2 points to the first 
bit in a block of 400 bits reserved in pixarray. The symbol VEC points to 
the first bit reserved in the uninit-V section. 

Figure 5-11 shows how this example reserves space in the uninitialized 
sections. 


5-45 




usect 


Reserve Uninitialized Space 


0001 

0002 

0003 

0004 00000000 

0005 00000000 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 00000000 
0015 

0016 00000010 
00000020 

0017 

0018 

0019 

0020 

0021 

0022 

0023 00000190 
0024 

0025 00000030 
00000040 

0026 

0027 

0028 

0029 

0030 

0031 00000000 
0032 

0033 00000050 

0034 

0035 

0036 

0037 

0038 


***************************************** 

* Begin assembling into .text * 

***************************************** 

. text 

5600 CLR AO 

***************************************** 

* Reserve 400 bits in the named section * 

* pixarray. Space is reserved for a var-* 

* iable named ar—1; ar_l is an array of * 

* 100 4-bit pixels. The space is aligned* 

* on a word boundary. * 

***************************************** 

ar_1 .usect "pixarray", 100 * 4, 1 

0B00 ADDI 36, A0 ; Still in .text 

0024 

***************************************** 

* Reserve 400 additional bits in section* 

* pixarray. This time, the space is re- * 

* served for a variable named ar_2. * 

***************************************** 

ar—2 .usect "pixarray", 100 *4,1 

0B00 ADDI 48, A0 ; Still in .text 

0030 

***************************************** 

* Reserve 32 bits in the named section * 

* uninit—V for the variable VEC. * 

***************************************** 

VEC .usect "uninit—V", 32, 1 

4C02 MOVE A0, A2 ; Still in .text 

***************************************** 

* Declare .usect symbols as external * 
***************************************** 

.global ar-1, ar_2, VEC 
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Initialize Word 


.word 


Syntax 

.word valuej [, ..., value n ] 

Description 

The .word directive places one or more values into consecutive 16-bit 
words in the current section. The assembler evaluates each expression and 
places the value in a word as a 16-bit number. You can use as many values 
as fit on a single line. 


Note: 


If the value is a relocatable expression, the assembler truncates it to a 
16-bit expression without warning. 

Example 

This example initializes five words. The symbol wordx points to the first 
word. 

0001 00000000 
00000010 
00000020 
00000030 
00000040 

0C80 WORDX: .word 3200,1+'AB ' ,-'AF',0F4A0h,'A' 

4242 

B9BF 

F4A0 

0041 
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Assembler Directives 
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Section 6 


Instruction Set 


The TMS34010 supports a base set of general-purpose instructions as well 
as special-purpose instructions that are particularly suited for graphics appli¬ 
cations. 

This section does not cover topics such as opcodes or instruction timing; the 
TMS34010 User's Guide discusses the instruction set in detail. The 
TMS34010 User's Guide also contains an alphabetical presentation which is 
similar to the directives reference that begins on page 5-14. 

This section provides a general summary of the TMS34010 instruction set. 
Section 6.1 provides an overview of the TMS34010 operand formats and de¬ 
scribes symbols that are used throughout this section. Section 6.2 lists the 
syntax, operation, and description of each instruction, Section 6.3 through 
Section 6.9 describe the functional categories of the instruction set. 


Section Page 

6.1 Overview of Operand Formats .6-2 

6.2 Summary Table .6-5 

6.3 Arithmetic, Logical, and Compare Instructions .6-22 

6.4 Move Instructions. 6-24 

6.5 Graphics Instructions .6-26 

6.6 Program Control and Context Switching Instructions .6-29 

6.7 Jump Instructions .6-30 

6.8 Shift Instructions .6-32 

6.9 XY Instructions .6-33 
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Instruction Set - Overview of Operand Formats 


6.1 Overview of Operand Formats 

The TMS34010 instruction set supports eight categories of operand formats. 
Most instructions have register-direct operands or a combination of register- 
direct and immediate operands. The MOVE, MOVB, and graphics instructions, 
however, use more complex combinations of operands. 

This section describes the symbols that are used in the instruction syntaxes to 
show operands formats. 


• Immediate Values and Constants 

An instruction syntax may use one of these symbols to indicate an immediate 
source operand: 

!W is a 16-bit (short) signed immediate value. 

IL is a 32-bit (long) signed immediate value. 

K is a 5-bit constant. 

Instructions that have immediate source operands have register-direct desti¬ 
nation operands. Many instructions that have an immediate value can use ei¬ 
ther a short or a long value. Here's an example of an instruction that uses an 
immediate operand: 

ADDI 36h, AO 

This example adds an immediate value, 36h, to the contents of register AO. 

• Absolute Addresses 

An instruction syntax may use one of these symbols to indicate an absolute 
operand: 

@SAc/c/ress is a source address that contains the source data. 

@DAd dress is a destination address. 

Note that the @ character is entered as part of the operand (this distinguishes 
it from an immediate operand). Here are two examples of instructions that use 
absolute operands: 

MOVB @loop, A4 
MOVE B2, @100h+2h 

The first instruction moves a byte from the address specified by the symbol 
loop into register A4. The second instruction moves the contents of register 
B2 into address 1 02h. 

• Register-Direct Operands 

An instruction syntax may use one of these symbols to indicate a register- 
direct operand: 

Rs is a source register that contains the source data. 

Rd is a destination register that will contain the result. 
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Instruction Set - Overview of Operand Formats 


When both operands of an instruction are register-direct operands, the regis¬ 
ters must be in the same file . (The MOVE Rs, Rd instruction is an exception 
to this rule.) Here's an instruction that uses two register-direct operands: 

ADD AO, A4 

This instruction adds the contents of register AO to the contents of register A4 
and leaves the result in A4. 

• Register-Indirect Operands 

An instruction syntax may use one of these symbols to indicate a register- 
indirect operand: 

* Rs is a register that contains the address of the source data. 

*Rd is a register that contains the destination address. 

Note that the * character is entered as part of the operand (this distinguishes 
it from a register-direct operand). Here's an instruction that uses two regis¬ 
ter-indirect operands: 

MOVE *AO, *A4 

Register AO contains an address and register A4 contains an address. This 
instruction moves the data from the address specified by AO into the address 
specified by A4. 

• Register-Indirect with Offset 

An instruction syntax may use one of these symbols to indicate a register- 
indirect operand that uses a signed offset: 

*Rs( offset) is a source address formed by adding an offset to the contents 
of the source register. 

*Rd(offset) is a destination address formed by adding an offset to the 
contents of the destination register. 

The offset is only used to form an address - the contents of the register are not 
affected. 

Note that the * character is entered as part of the operand. Here's an example 
that uses a register-indirect source operand with a displacement: 

MOVE A4, *A3(16) 

This instruction moves the data in register A4 to a destination address. The 
destination address is formed by adding the offset, 16, to the contents of reg¬ 
ister A3. 

• Register-Indirect with Postincrement 

An instruction syntax may use one of these symbols to indicate a register- 
indirect operand that is postincremented: 

*Rs+ is a register that contains the address of the source data. 

*Rd+ is a register that contains the destination address. 

After the operation is performedthe contents of the specified source or desti¬ 
nation register are incremented by the field size used for the operation. 
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Instruction Set - Overview of Operand Formats 


Note that the * and + characters are entered as part of the operand. Here's 
an example that uses an indirect destination operand with postincrement: 

MOVE A4, *A5+, 1 

This instruction moves the contents of register A4 to the address specified by 
the contents of A5. The third operand, 1, indicates that FS1 and FE1 should 
be used for this move. After the data is moved, the contents of FS1 are added 
to the contents of A5. 

• Register-Indirect with Predecrement 

An instruction syntax may use one of these symbols to indicate a register- 
indirect operand that is predecremented. 

Before the operation is performed , the contents of the specified source or 
destination register are decremented by the field size used for the operation. 

*-Rs the decremented register contents are the address of the source data. 
*-Rd the decremented register contents specify the destination address. 

Note that the * and - characters are entered as part of the operand. Here's an 
example that uses an indirect source operand with predecrement: 

MOVE *-A4, A5, 0 

The third operand of this instruction, 0, indicates that FSO and FEO should be 
used for this move. Before the move is performed, the contents of FSO are 
subtracted from the contents of register A4 to produce the source address. The 
contents of this address are moved into register A5. 

• Register-Indirect in XY Mode 

An instruction syntax may use one of these symbols to indicate that the a re¬ 
gister operands contains an XY address. 

*Rs.X Y is a register that contains the XY address of the source data. 

*Rd.X Y is a register that contains the XY destination address. 

Note that the * and .XY characters are entered as part of the operand. Here's 
an example that uses an indirect-XY destination operand: 

PIXT AO, *A6.XY 

This instruction moves the contents of register AO into the XY address speci¬ 
fied by the contents of register A6. 
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Instruction Set - Summary Table 


6.2 Summary Table 


Syntax 

Description 

ABS Rd 

Store Absolute Value 

Operation: | Rd I -+ Rd 

Store the absolute value of the specified register back into the register. 

ADD Rs. Rd 

Add Registers 

Operation: Rs + Rd -* Rd 

Add the contents of the source register to the contents of the destination 
register. 

ADDC Rs, Rd 

Add Registers with Carry 

Operation: Rs + Rd + C -*■ Rd 

Add the contents of the source register and the carry bit to the contents 
of the destination register. 

ADDI IW, Rd, [\N] 

ADDI IL, Rd, [L] 

Add Immediate - Short or Long 

Operation: immediate value + Rd Rd 

Add an immediate value to the contents of the destination register. In the 
short form, the operand is a 16-bit sign-extended value. In the long form, 
the operand is a 32-bit signed value. 

You can force the assembler to use the short (16-bit) form of this in¬ 
struction by using the W operand. You can force the assembler to use the 
long (32-bit) form of this instruction by using the L operand. 

ADDK K, Rd 

Add Constant (5 Bits) 

Operation: K + Rd -* Rd 

Add a 5-bit constant to the contents of the destination register. 

The constant K is treated as an unsigned number in the range 1-32; K=32 
is converted to 0 in the opcode. The assembler issues an error if you try 
to add 0 to a register. 

ADDXY Rs, Rd 

Add Registers in XY Mode 

Operation: RsX + RdX -* RdX 

RsY + RdY -> RdY 

The registers are signed XY registers. Add the X half of the source register 
to the X half of the destination register, and add the Y half of the source 
register to the Y half of the destination register. All the values are signed. 
Any carry out from the X portion does not propagate into the Y portion. 

AND Rs, Rd 

AND Registers 

Operation: RsAND Rd -> Rd 

Bitwise-AND the contents of the source register with the contents of the 
destination register. 


Key: 

Rs - Source register Rd 

RsX, RdX - X half (16 LSBs) of Rs or Rd RsY, RdY 

SAddress - 32-bit source address DAddress 

IW - 16-bit (short) immediate value IL 

Address - 32-bit address (label) F 

K - 5-bit constant 

PC' - Next instruction 


Destination register 
Y half (16 MSBs) of Rs or Rd 
32-bit destination address 
32-bit (long) immediate value 
Field select; defaults to 0 
F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

ANDI /L, Rd 

AND Immediate (32 Bits) 

Operation: ILANDRd-*Rd 

Bitwise-AND a 32-bit immediate value with the contents of the destination 
register. 

AN DIM Rs, Rd 

AND Register with Complement 

Operation: (NOT Rs) AND Rd -> Rd 

Bitwise-AND the Is complement of the source register contents with the 
contents of the destination register. 

ANDNI IL, Rd 

AND Not Immediate (32 Bits) 

Operation: (NOT IL) AND Rd Rd 

Bitwise-AND the Is complement of a 32-bit immediate value with the 
contents of the destination register. 

BTST K, Rd 

Test Register Bit - Constant 

Operation: set status on value of bit K in Rd 

Test bit K in the destination register, and set the Z bit. If K=0, set Z to 1; 
if K=1, set Z to 0. 

BTST Rs, Rd 

Test Register Bit - Register 

Operation: Rs specifies a bit number; set status on value of this bit in Rd 

Rs specifies the bit number to test. Test this bit in the destination register, 
and set the Z bit. If the bit is 0, set Z to 1; if the bit is 1, set Z to 0. 

CALL Rs 

Call Subroutine - Indirect 

Operation: PC' -► TOS 

Rs PC 

SP -32 -> SP 

Rs specifies the address of a subroutine. The assembler pushes the address 
of the next instruction (PC') onto the stack, then jumps to address of the 
subroutine. Note that when Rs=SP, Rs is decremented after it is written 
to the PC (the PC contains the original value of Rs). 

CALLA Address 

Call Subroutine - Absolute 

Operation: PC' -* TOS 

Address -* PC 

The assembler pushes the address of the next instruction (PC') onto the 
stack, then jumps to the specified 32-bit address. 

CALLR Address 

Call Subroutine - Relative 

Operation: PC' -*■ TOS 

PC' + (displacement x 16) -► PC 

The assembler pushes the address of the next instruction (PC') onto the 
stack, then jumps to the address specified by PC' + displacement. The 
address must be within the current section. 

CLR Rd 

Clear Register 

Operation: Rd XOR Rd -*■ Rd 

Set the contents of the register to 0. 

CLRC 

■ 

Clear Carry 

Operation: 0 -*■ C 

Set the contents of the carry bit to 0. 
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Instruction Set - Summary Table 


Syntax 


CMP Rs, Rd 


CMPI IW, Rd, [\N] 
CM PI !L,Rd,[L] 


CMPXY Rs, Rd 



CVXYL Rs, Rd 


Description 


Compare Registers 

Operation : set status bits on the result of Rd - Rs 

Set the status bits as if the contents of the source register were subtracted 
from the contents of the destination register. This is a nondestructive 
compare - the register contents do not change. 


Compare Immediate - Short or Long 

Operation : set status bits on the result of Rd - immediate value 

Set the status bits as if an immediate value were subtracted from the con¬ 
tents of the destination register. This is a nondestructive compare - the 
register contents do not change. CMPI is used with conditional jumps. 
In the short form, the operand is a 16-bit sign-extended value. In the long 
form, the operand is a 32-bit signed value. 

You can force the assembler to use the short (16-bit) form of this in¬ 
struction by using the W operand. You can force the assembler to use the 
long (32-bit) form of this instruction by using the L operand. 


Compare X and Y Halves of Registers 

Operation : set status bits on the results of: 

RdX - RsX 
RdY - RsY 

The registers are signed XY registers. Set the status bits as if RsX were 
subtracted from RdX and RsY were subtracted from RdY. No overflow 
detection is provided. This is a nondestructive compare - the register 
contents do not change. 


Compare Point to Window 

Operation : point code -»• Rd 

The source register contains an XY address. The assembler compares this 
address to the window limits defined by the WSTART and WEND registers. 
Bits 5-8 of the destination register are set to a 4-bit code that identifies the 
location of the specified address with respect to the window. The follow¬ 
ing diagram shows the codes in relation to the window; the upper left 
corner is at address [0,0]. 


0101 

0100 

0110 

0001 

0000 

(window) 

0010 

1001 

1000 

1010 


Convert XY Address to Linear Address 

Operation : XY address in Rs linear address in Rd 

Convert the XY address in the source register to a linear address that is 
placed in the destination register. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd 

RsY, RdY 


Destination register 
Y half (16 MSBs) of Rs or Rd 


DAddress - 32-bit destination address 
IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

DEC Rd 

Decrement Register 

Operation: Rd - 1 -* Rd 

Subtract 1 from the contents of the destination register. 

DINT 

Disable Interrupts 

Operation: 0 -*■ IE 

Disable interrupts by setting the global interrupt enable bit (IE) to 0. 

DIVS Rs, Rd 

Divide Registers - Signed 

Operation: Rd even: Rd:Rd + 1 / Rs -* Rd 

Remainder Rd + 1 

Rd odd: Rd / Rs -> Rd 

Perform a signed divide. There are two cases: 

Rd even: The contents of Rd and the contents of the next consecutive 
register (Rd + 1) form a 64-bit operand. Rd specifies the 32 MSBs and 
Rd + 1 specifies the 32 LSBs. The 64-bit operand is divided by the contents 
of the source register. The result is stored in Rd, and the remainder is 
stored in Rd + 1. The remainder and the result always have the same sign. 

Rd odd: Divide the contents of the destination register by contents of the 
source register. The destination register contains the result; the remainder 
is not stored. 

DIVU Rs, Rd 

Divide Registers - Unsigned 

Operation: Rd even: Rd:Rd + 1 / Rs Rd 

Remainder -* Rd + 1 

Rd odd: Rd / Rs -> Rd 

Perform an unsigned divide. There are two cases: 

Rd even: The contents of Rd and the contents of the next consecutive 
register (Rd + 1) form a 64-bit operand. Rd specifies the 32 MSBs and 
Rd + 1 specifies the 32 LSBs. The 64-bit operand is divided by the contents 
of the source register. The result is stored in Rd, and the remainder is 
stored in Rd + 1. The remainder and the result always have the same sign. 

Rd odd: Divide the contents of the destination register by contents of the 
source register. The destination register contains the result; the remainder 
is not stored. 

DRAV Rs, Rd 

Draw and Advance 

Operation: C0L0R1 pixel value -+ *Rd 

RsX + RdX -> RdX 

RsY + RdY -> RdY 

Write the pixel value in the C0L0R1 register to the XY address contained 
in Rd, then increment the X half of Rd by RsX and the Y half of Rd by RsY. 
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Instruction Set - Summary Table 


Syntax 

Description 

DSJ Rd, Address 

DSJS Rd, Address 

Decrement Register and Skip Jump - Short or Long 

Operation: Rd - 1 -+ Rd 

If Rd ^ 0, then (displacement x 16) + PC' -> PC 

If Rd = 0, then go to next instruction 

Decrement the contents of the destination register by 1. 

If the result is nonzero, then jump to the address specified by (displace¬ 
ment x 16) + PC'. 

If the result is 0, then skip the jump and continue execution at PC'. 

This instruction has a short form and a long form. The assembler auto¬ 
matically chooses the short form if the displacement is 5 bits or less, which 
provides a jump range of ±32 words (excluding 0). The assembler auto¬ 
matically chooses the long form if the displacement is greater than 5 bits, 
which provides a jump range of -32,768 to +32,767. 

D SJ EQ Rd, A ddress 

Conditionally Decrement Register and Skip Jump 

Operation: If Z = 1: 

Rd - 1 -► Rd 

If Rd 5 * 0, then (displacement x 16) + PC' -> PC 

If Rd = 0, then go to next instruction 

If Z = 0 go to next instruction 

If Z=1 , subtract 1 from the contents of the destination register. If the result 
is nonzero, then jump to the address specified by (displacement x 16) + 
PC'. If the result is 0, then skip the jump and continue execution at PC'. 

If Z=0, skip the jump and continue execution at PC'. 

DSJNE Rd, Address 

Conditionally Decrement Register and Skip Jump 

Operation: If Z = 0: 

Rd - 1 Rd 

If Rd & 0, then (displacement x 16) + PC' -> PC 

If Rd = 0, then go to next instruction 

If Z = 1 go to next instruction 

If Z=0, subtract 1 from the contents of the destination register. If the result 
is nonzero, then jump to the address specified by (displacement x 16) + 
PC'. If the result is 0, then skip the jump and continue execution at PC'. 

If Z=1, skip the jump and continue execution at PC'. 

EINT 

Enable Interrupts 

Operation: 1 -+ IE 

Set the global interrupt enable bit (IE) to 1. Individual interrupts can now 
be enabled by setting the appropriate bits in the INTENB register. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

DAddress - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

EMU 

Initiate Emulation 

Operation: ST -* Rd 

conditionally enter emulator mode 

Pulse the EMUA pin and sample the RUN/EMU pin. If RUN/EMU is in the 
RUN state, the EMU instruction acts as a NOP. If the pin is in the EMU 
state, the processor enters emulation mode. 

EXGF Rd [, F] 

Exchange Field Size 

Operation: Rd -► FSO, FEO or Rd FS1, FE1 

FSO, FEO Rd or FS1, FE1 -♦ Rd 

Exchange the 6 LSBs of the destination register with the selected 6 bits of 
field information. F is an optional parameter that can be 0 or 1. If you 
specify 0, then FSO and FEO are selected; if you specify 1, then FS1 and 
FE1 are selected. FSO and FEO are the default. Bit 5 of the 5-bit value in 
Rd is exchanged with the field extension value. The 26 MSBs of Rd are 
cleared. 

EXGPC Rd 

Exchange Program Counter 

Operation: Rd -* PC 

PC' -> Rd 

Exchange the next program counter value with the contents of the desti¬ 
nation register. After EXGPC completes executing, Rd contains the address 
of the instruction that immediately follows the EXGPC. 

FILL L 

Fill Array with Processed Pixels - Linear 

Operation: COLOR1 pixel values -* pixel array (with processing) 

Combine an array of source pixels (specified by COLOR1) with a destina¬ 
tion pixel array, based on the selected graphics operations. The address 
of the destination array is a linear address. 

FILL XY 

Fill Array with Processed Pixels - XY 

Operation: C0L0R1 pixel values pixel array (with processing) 

Combine an array of source pixels (specified by COLOR1) with a destina¬ 
tion pixel array, based on the selected graphics operations. The address 
of the destination array is an XY address. 

GETPC Rd 

Get Program Counter into Register 

Operation: PC' -* Rd 

Increment the PC to point to the next instruction, and copy that address 
into the destination register. 

GETST Rd 

Get Status Register into Register 

Operation: ST -> Rd 

Copy the contents of the status register into the destination register. 

INC Rd 

Increment Register 

Operation: PC + 1 -* Rd 

Add 1 to the contents of the destination register. 

JA cc Address 

Jump Absolute Conditional 

Operation: If cc = true, then Address -* PC 

If cc = false, then go to next instruction 

If the condition is true, jump to the address. If the condition is false, 
continue execution at PC', cc is one of the condition codes listed in Table 
6-11 on page 6-33. 
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Instruction Set - Summary Table 


Syntax 

Description 

JRcc Address 

Jump Relative Conditional 

Operation: If cc = true, then displacement + PC' -+ PC 

If cc = false, then go to next instruction 

If the condition is true, jump to the address specified by displacement + 
PC'. If the condition is false, continue execution at PC', cc is one of the 
condition codes listed in Table 6-11 on page 6-33. 

This instruction has a short form and a long form. The assembler auto¬ 
matically chooses the short form if the displacement is 8 bits or less; this 
provides a jump range of ±127 words excluding 0). The assembler auto¬ 
matically chooses the long form if the displacement is greater than 8 bits; 
this provides a jump range of ±32K words excluding 0). 

JUMP Rs 

Jump Indirect 

Operation: Rs PC 

Jump to the address specified by the source register. 

LINE [0 , \] 

Line Draw with XY Addressing 

Operation: LINE 0 

While COUNT > 0 

Draw the next pixel 

If o'> 0 

d = d + 2b - 2 a 

POINTER = POINTER + INC1 

Else 

d = d + 2b 

POINTER = POINTER + INC2 

LINE 1 

While COUNT > 0 

Draw the next pixel 

If d> 0 

d = d + 2b - 2 a 

POINTER = POINTER + INC1 

Else 

d = d + 2b 

POINTER = POINTER + INC2 

Perform the inner loop of Bresenham's line-drawing algorithm. 

LMO Rs, Rd 

Leftmost One 

Operation: 31 - bit number of leftmost 1 in Rs -*■ Rd 

Locate the leftmost 1 in the source register. Load the Is complement of 
the bit number of the leftmost one into the 5 LSBs of the destination reg¬ 
ister. The 27 MSBs of Rd are zeroed. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd ~ Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

DAddress - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

MMFM Rs [, reg. list] 

Move Multiple Registers from Memory 

Operation: If Register n is in the register list, 

*Rsh—► Ra? (repeat for n = 0 to 15) 

Load the contents of a specified list of either A or B registers (not both) 
from a block of memory. Rs points to the first location in the memory 
block; Rs and the registers in the list must be in the same file. If you don't 
specify a register list, all the registers that are in the same file as Rs are 
moved. 

MMTM Rd[. reg. list] 

Move Multiple Registers to Memory 

Operation: If Register n is in the register list, 

R n -> - * Rd (repeat for n - 0 to 1 5) 

Store the contents of a specified list of either A or B registers (not both) 
into a block of memory. Rd points to the first location in the memory block; 
Rd and the registers in the list must be in the same file. If you don't specify 
a register list, all the registers that are in the same file as Rd are moved. 

MODS Rs, Rd 

Modulus - Signed 

Operation: Rd mod Rs -> Rd 

Divide the contents of the destination register by the contents of the source 
register, and load the remainder into the destination register. The contents 
of the registers are treated as signed numbers. 

MODU Rs, Rd 

Modulus - Unsigned 

Operation: Rd mod Rs -> Rd 

Divide the contents of the destination register by the contents of the source 
register, and load the remainder into the destination register. The contents 
of the registers are treated as signed numbers. 

MOVB Rs, *Rd 

Move Byte - Register to Indirect 

Operation: Rs -*• *Rd 

Move the least significant byte of the source register to a memory address. 
The destination address is specified by the contents of the destination re¬ 
gister. 

MOVB Rs, * Rd [offset) 

Move Byte - Register to Indirect with Offset 

Operation: Rs -*■ *(Rd + offset) 

Move the least significant byte of the source register to memory. The me¬ 
mory address is formed by adding the offset to the contents of the desti¬ 
nation register. 

MOVB Rs, @DAddress 

Move Byte - Register to Absolute 

Operation: Rs -► (S)DAddress 

Move the least significant byte of the source register to the specified me¬ 
mory address. 

MOVB *Rs, Rd 

Move Byte - Indirect to Register 

Operation: *Rs -* Rd 

Move a byte from a memory location into the destination register; the byte 
is right-justified and sign-extended within Rd. The source address is spe¬ 
cified by the contents of the source register. 
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Instruction Set - Summary Table 


Syntax 

Description 

MOVB *Rs, *Rd 

Move Byte - indirect to Indirect 

Operation: *Rs *Rd 

Move a byte from a memory location into another memory location. The 
source address is specified by the contents of the source register, and the 
destination address is specified by the contents of the destination register. 

MOVB *Rs(offset), Rd 

Move Byte - Indirect with Offset to Register 

Operation: *(Rs + offset) -*■ Rd 

Move a byte from a memory location into the destination register; the byte 
is right-justified and sign-extended within Rd. The source address is 
formed by adding the offset to the contents of the source register. 

MOVB *Rs(offset), *Rd( 

offset) 

Move Byte - Indirect with Offset to Indirect with Offset 

Operation: *(Rs + offset) -► *(Rd + offset) 

Move a byte from a memory location into another memory location. The 
source address is formed by adding an offset to the contents of the source 
register, and the destination address is formed by adding an offset to the 
contents of the destination register. 

MOVB @ SAddress, Rd 

Move Byte - Absolute to Register 

Operation: (a>SAddress -► Rd 

Move a byte from a memory location to the destination register. 

MOVB @SAddress, @DA 

ddress 

Move Byte - Absolute to Absolute 

Operation: (a)SAddress (a>DAddress 

Move a byte from a memory location into another memory location. 

MOVE Rs, Rd 

Move - Register to Register 

Operation: Rs -* Rd 

Move the contents of the source register into the destination register. It is 
not necessary for the registers to be in the same file . 

MOVE Rs, *Rd[, F] 

Move Field - Register to Indirect 

Operation: field in Rs -* field in *Rd 

Move a field from the source register into a memory location specified by 
the contents of the destination register. 

MOVE Rs, *Rd+ [, F] 

Move Field - Register to Indirect (Postincrement) 

Operation: field in Rs -*■ field in *Rd 

Rd + field size Rd 

Move a field from the source register into a memory location specified by 
the contents of the destination register. After the move, increment the 
contents of Rd by the field size. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

□Address - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

MOVE Rs, -*Rd[, F] 

Move Field - Register to Indirect (Predecrement) 

Operation: Rd - field size -> Rd 

field in Rs -+ field in *Rd 

Decrement the contents of Rd by the field size. Move a field from the 
source register into a memory location specified by the contents of the 
destination register. 

MOVE Rs, *Rd(offset) [, F] 

Move Field - Register to Indirect with Offset 

Operation: field in Rs -> field in *(Rd + offset) 

Move a field from the source register into a memory location. The desti¬ 
nation address is formed by adding an offset to the contents of the desti¬ 
nation register. 

MOVE Rs, @DAddress [, F] 

Move Field - Register to Absolute 

Operation: field in Rs field in memory 

Move a field from the source register into the specified destination address. 

MOVE *Rs, Rd [, F] 

Move Field - Indirect to Register 

Operation: field in *Rs field in Rd 

Move a field from contents of a memory address into the destination reg¬ 
ister. The source address is specified by the contents of the source register. 

MOVE *Rs, *Rd [, F] 

Move Field - Indirect to Indirect 

Operation: field in *Rs -* field in *Rd 

Move a field from the contents of a memory address into another memory 
address. The source address is specified by the contents of the source re¬ 
gister, and the destination address is specified by the contents of the des¬ 
tination register. 

MOVE *Rs+, Rdf, F] 

Move Field - Indirect (Postincrement) to Register 

Operation: field in *Rs -*• field in Rd 

Rs + field size Rs 

Move a field from the contents of a memory address into the destination 
register. The source address is specified by the contents of the source re¬ 
gister. After the move, increment the contents of the source register by the 
field size. 

MOVE *Rs+, *Rd+ [, F] 

Move Field - Indirect (Postincrement) to Indirect (Postincre¬ 
ment) 

Operation: field in *Rs -*■ field in *Rd 

Rs + field size -* Rs 

Rd + field size -> Rd 

Move a field from the contents of a memory address into another memory 
address. The source address is specified by the contents of the source re¬ 
gister, and the destination address is specified by the contents of the des¬ 
tination register. After the move, increment the contents of both the source 
register and the destination register by the field size. 

MOVE - *Rs, Rd [, FJ 

Move Field - Indirect (Predecrement) to Register 

Operation: Rs - field size Rs 

field in *Rs -* field in Rd 

Decrement the contents of the source register by the field size. Move a 
field from the contents of a memory address into the destination register. 
The source address is specified by the contents of the source register. 
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Instruction Set - Summary Table 


Syntax 

Description 

MOVE - * Rs, -*Rd [, F] 

Move Field - Indirect (Predecrement) to Indirect (Predecrement) 

Operation: Rs - field size -* Rs 

Rd - field size -+ Rd 
field in *Rs -* field in *Rd 

Decrement the contents of both the source register and the destination re¬ 
gister by the field size. Move a field from the contents of a memory address 
into another memory address. The source address is specified by the con¬ 
tents of the source register, and the destination address is specified by the 
contents of the destination register. 

MOVE * Rs(offset), Rd [, 

F] 

Move Field - Indirect with Offset to Register 

Operation: field in *(Rs + offset) field in Rd 

Move a field from the contents of a memory address into the destination 
register. The source address is formed by adding an offset to the contents 
of the source register. 

MOVE *Rs{offset), *Rd+ 

[' F] 

Move Field - Indirect with Offset to Indirect (Postincrement) 

Operation: field in *(Rs + offset) -* field in *Rd 

Move a field from the contents of a memory address into the destination 
register. The source address is formed by adding an offset to the contents 
of the source register. After the move, increment the contents of the des¬ 
tination register by the field size. 

MOVE *Rs(offset), *Rd(i 

offset) [, F] 

Move Field - Indirect with Offset to Indirect with Offset 

Operation: field in *(Rs + offset) -+ field in *(Rd + offset) 

Move a field from the contents of a memory address into another memory 
address. The source address is formed by adding an offset to the contents 
of the source register, and the destination address is formed by adding an 
offset to the contents of the destination register. 

MOVE ©SAddress, Rdf, 

F] 

Move Field - Absolute to Register 

Operation: field in source address -» field in Rd 

Move a field from the contents of the specified memory address into the 
destination register. 

MOVE @ SAddress, *Rd+ 

[■ F] 

Move Field - Absolute to IndirectfPostincrement) 

Operation: field in source address field in *Rd 

Rd + field size Rd 

Move a field from the contents of the specified source address into the 
memory address specified by the contents of the destination register. After 
the move, increment the contents of the destination register by the field 
size. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

DAddress - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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instruction Set - Summary Table 


Syntax | 

1 Description 

MOVE @S Address, @D Address [, F] 

Move Field - Absolute to Absolute 

Operation: field in source address -* field in destination address 

Move a field from the contents of the specified source address into the 
specified destination address. 

MOV! IW, Rd, f\N] 

MOVI !L, Rd, [L] 

Move Immediate - Short or Long 

Operation: immediate operand -+ Rd 

Move an immediate value into the destination register. In the short form, 
the operand is a 16-bit sign-extended value. In the long form, the operand 
is a 32-bit signed value. 

You can force the assembler to use the short (16-bit) form of this in¬ 
struction by using the W operand. You can force the assembler to use the 
long (32-bit) form of this instruction by using the L operand. 

MOVK K, Rd 

Move Constant - 5 Bits 

Operation: K -* Rd 

Move a 5-bit constant into the destination register. Note that this in¬ 
struction does not affect the status register. 

MOVX Rs, Rd 

Move X Half of Register 

Operation: RsX RdX 

Move the X half (16 LSBs) of the source register into the X half of the 
destination register. The Y portions are not affected. 

MOVY Rs, Rd 

Move Y Half of Register 

Operation: RsY RdY 

Move the Y half (16 LSBs) of the source register into the Y half of the 
destination register. The X portions are not affected. 

MPYS Rs, Rd 

Multiply Registers - Signed 

Operation: Rd even: Rs x Rd Rd:Rd + 1 

Rd odd: Rs x Rd -* Rd 

Perform a signed multiply of a field in the source register by the 32-bit 
contents of the destination register. This produces a 32-bit to a 64-bit re¬ 
sult, depending on the register and the field definition. 

MPYU Rs, Rd 

Multiply Registers - Unsigned 

Operation: Rd even: Rs x Rd -* Rd:Rd + 1 

Rd odd: Rs x Rd -*■ Rd 

Perform an unsigned multiply of a field in the source register by the 32-bit 
contents of the destination register. This produces a 32-bit to a 64-bit re¬ 
sult, depending on the register and the field definition. 

NEG Rd 

Negate Registers 

Operation: -Rd -> Rd 

Store the 2s complement of the contents of the destination register back 
into the destination register. 

NEGB Rd 

Negate Registers with Borrow 

Operation: -Rd - C -► Rd 

Take the 2s complement of the contents of the destination register; if the 
carry bit is set, decrement the result by 1. 
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Instruction Set - Summary Table 


Syntax 

Description 

NOP 

No Operation 

Operation: no operation 

Increment the program counter to point to the next instruction. 

NOT Rd 

Complement Register 

Operation: NOT Rd Rd 

Store the Is complement of the contents of the destination register back 
into the destination register. 

OR Rs, Rd 

OR Registers 

Operation: Rs OR Rd -► Rd 

Bitwise-OR the contents of the source register with the contents of the 
destination register. 

ORI IL, Rd 

OR Immediate 

Operation: IL OR Rd Rd 

Bitwise-OR a 32-bit immediate value with the contents of the destination 
register. 

PIXBLT B, L 

Pixel Block Transfer - Binary to Linear 

Operation: binary source pixel array destination pixel array 
(with processing) 

Expand, transfer, and process a source pixel array with a destination pixel 
array according to the selected graphics operations. The starting addresses 
for both arrays are linear addresses. The source array contains 1 -bit pixels. 

PIXBLT B, XY 

Pixel Block Transfer - Binary to XY 

Operation: binary source pixel array -► destination pixel array 
(with processing) 

Expand, transfer, and process a source pixel array with a destination pixel 
array according to the selected graphics operations. The starting address 
of the source array is a linear address; the starting address of the destination 
array is an XY address. The source array contains 1 -bit pixels. 

PIXBLT L, L 

Pixel Block Transfer - Linear to Linear 

Operation: source pixel array -* destination pixel array (with processing) 

Transfer and process a source pixel array with a destination pixel array ac¬ 
cording to the selected graphics operations. The starting addresses of both 
arrays are linear addresses. 

PIXBLT L, XY 

Pixel Block Transfer - Linear to XY 

Operation: source pixel array -> destination pixel array (with processing) 

Transfer and process a source pixel array with a destination pixel array ac¬ 
cording to the selected graphics operations. The starting address of the 
source array is a linear address; the starting address of the destination array 
is an XY address. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

DAddress - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Instruction Set - Summary Table 


Syntax 

Description 

PIXBLT XY, L 

Pixel Block Transfer - XY to Linear 

Operation: source pixel arrav -* destination pixel array (with processing) 

Transfer and process a source pixel array with a destination pixel array ac¬ 
cording to the selected graphics operations. The starting address of the 
source array is an XY address; the starting address of the destination array 
is a linear address. 

PIXBLT XY, XY 

Pixel Block Transfer - XY to XY 

Operation: source pixel array destination pixel arrav (with processing) 

Transfer and process a source pixel array with a destination pixel array ac¬ 
cording to the selected graphics operations. The starting addresses of the 
both arrays are XY addresses. 

PIXT Rs, *Rd 

Pixel Transfer - Register to indirect 

Operation: pixel in Rs -* pixel in *Rd 

Transfer a pixel from the source register to the linear address specified by 
the contents of the destination register. 

PIXT Rs, *Rd.X Y 

Pixel Transfer - Register to Indirect XY 

Operation: pixel in Rs pixel in *Rd.XY 

Transfer a pixel from the source register to the XY address specified by the 
contents of the destination register. 

PIXT *Rs, Rd 

Pixel Transfer - indirect to Register 

Operation: pixel in *Rs -* pixel in Rd 

Transfer a pixel from a linear address to the destination register. The source 
address is specified by the contents of the source register. 

PIXT *Rs, *Rd 

Pixel Transfer - indirect to indirect 

Operation: pixel in *Rs -*■ pixel in *Rd 

Transfer a pixel from a linear address to another linear address. The source 
address is specified by the contents of the source register, and the desti¬ 
nation address is specified by the contents of the source destination regis¬ 
ter. 

PIXT */?s.XY, Rd 

Pixel Transfer - indirect XY to Register 

Operation: pixel in *Rs.XY pixel in Rd 

Transfer a pixel from an XY address to the destination register. The source 
address is specified by the contents of the source register. 

PIXT *Rs.X Y, *Rd.X Y 

Pixel Transfer - indirect XY to indirect XY 

Operation: pixel in *Rs.XY -> pixel in *Rd.XY 

Transfer a pixel from an XY address to another XY address. The source 
address is specified by the contents of the source register, and the desti¬ 
nation address is specified by the contents of the source destination regis¬ 
ter. 

POPST 

Pop Status Register from Stack 

Operation: *SP+ -*■ ST 

Move the two words on the top of the stack into the status register. After 
the move, increment the SP by 32. 
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Syntax 

Description 

PUSHST 

Push Status Register on Stack 

Operation: ST -+ -*SP 

Decrement the SP by 32, then move the contents of the status register onto 
the top of the stack. 

PUTST Rs 

Copy Register into Status 

Operation: Rs -> ST 

Copy the contents of the source register into the status register. 

RETI 

Return from Interrupt 

Operation: *SP+ ST 
*SP+ -> PC 

Return from an interrupt routine. Pop the status register and the program 
counter from the stack and continue executing from the address in the PC. 

RETS [NJ 

Return from Subroutine 

Operation: *SP PC (N defaults to 0) 

SP + 32 + 16N SP 

Return from a subroutine. Move the program counter from the stack and 
increment SP by 32 + 16N; if N is not specified, increment the SP by 32. 

REV Rc/ 

Store Revision Number 

Operation: revision number -* Rd 

Load the revision number of the TMS34010 into the destination register. 

RL K, Rd 

Rotate Left - Constant 

Operation: Rd rotated left by K -► Rd 

Left-rotate the contents of the destination register by the value of K (K 
specifies a value between 0-31). 

RL Rs, Rd 

Rotate Left - Register 

Operation: Rd rotated left by Rs -► Rd 

Left-rotate the contents of the destination register by the value in the 5 
LSBs of the source register. (The 5 LSBs of the source register specify a 
value between 0-31; the 27 MSBs are ignored.) 

SETC 

Set Carry 

Operation: 1 -> C 

Set the carry bit to 1. 

SETF FS, FE [, F] 

Set Field Parameters 

Operation: (FS, FE) -* ST 

Load the values specified for the field size and field extension bits into the 
status register. The remainder of the status register is not affected. 

SEXT Rd [, F] 

Sign Extend to Long 

Operation: field in Rd -*■ sign-extended field in Rd 

Sign extend a field in the destination register by copying the MSB of the 
field into the nonfield bits. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K - 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 

DAddress - 32-bit destination address 

IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 
F=1 selects FS1 and FE1 
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Syntax 

Description 

SLA K, Rd 

Shift Left Arithmetic - Constant 

Operation: Left-shift Rd bv K -* Rd 

Left-shift the contents of the destination register by the value of K. (K 
specifies a value between 0-31.) Os are left-shifted into the LSBs and the 
last bit shifted out is shifted into the carry bit. If either the sign bit (N) or 
any bits shifted out of Rd differ from the original sign bit, the overflow (V) 
bit is set. 

SLA Rs, Rd 

Shift Left Arithmetic - Register 

Operation: left-shift Rd by Rs -+ Rd 

Left-shift the contents of the destination register by the value in the 5 LSBs 
of the source register. (The 5 LSBs of the source register specify a value 
between 0-31; the 27 MSBs are ignored.) Os are left-shifted into the LSBs 
and the last bit shifted out is shifted into the carry bit. If either the sign 
bit (N) or any bits shifted out of Rd differ from the original sign bit, the 
overflow (V) bit is set. 

SLL K, Rd 

Shift Left Logical - Constant 

Operation: left-shift Rd bv K Rd 

Left-shift the contents of the destination register by the value of K. (K 
specifies a value between 0-31.) Os are left-shifted into the LSBs and the 
last bit shifted out is shifted into the carry bit. Note that this instruction 
does not affect the overflow bit. 

SLL Rs, Rd 

Shift Left Logical - Register 

Operation: left-shift Rd bv Rs Rd 

Left-shift the contents of the destination register by the value in the 5 LSBs 
of the source register. (The 5 LSBs of the source register specify a value 
between 0-31; the 27 MSBs are ignored.) 0s are left-shifted into the LSBs 
and the last bit shifted out is shifted into the carry bit. Note that this in¬ 
struction does not affect the overflow bit. 

SRA K, Rd 

Shift Right Arithmetic - Constant 

Operation: right-shift Rd bv K -+ Rd 

Right-shift the contents of the destination register by the value of K. (K 
specifies a value between 0-31.) The original value of the sign bit (MSB) 
is shifted into the MSBs of Rd, the last bit shifted out is shifted into the 
carry bit. 

SR A Rs, Rd 

Shift Right Arithmetic - Register 

Operation: right-shift Rd by Rs -* Rd 

Right-shift the contents of the destination register by the 2s complement 
value of the 5 LSBs in the source register. (The 5 LSBs of the source re¬ 
gister specify a value between 0-31; the 27 MSBs are ignored.) The ori¬ 
ginal value of the sign bit (MSB) is shifted into the MSBs of Rd, the last 
bit shifted out is shifted into the carry bit. 

SRL K, Rd 

Shift Right Logical - Constant 

Operation: right-shift Rd by K -* Rd 

Right-shift the contents of the destination register by the value of K. (K 
specifies a value between 0-31.) 0s are shifted into the MSBs of Rd, and 
the last bit shifted out is shifted into the carry bit. 

SRL Rs, Rd 

Shift Right Logical - Register 

Operation: right-shift Rd by Rs -+ Rd 

Right-shift the contents of the destination register by the 2s complement 
value of the 5 LSBs in the source register. (The 5 LSBs of the source re¬ 
gister specify a value between 0-31; the 27 MSBs are ignored.) 0s are 
shifted into the MSBs of Rd, and the last bit shifted out is shifted into the 
carry bit. 
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Syntax 

Description 

SUB Rs, Rd 

Subtract Registers 

Operation: Rd - Rs Rd 

Subtract the contents of the source register from the contents of the des¬ 
tination register. 

SUBB Rs, Rd 

Subtract Registers with Borrow 

Operation: Rd - Rs - C -+ Rd 

Subtract the contents of the source register and the carry bit from the 
contents of the destination register. 

SUBI IW, Rd, f\NJ 

SUBI IL, Rd, [LJ 

Subtract Immediate - Short or Long 

Operation: Rd - immediate value -> Rd 

Subtract an immediate value from the contents of the destination register. 
In the short form, the operand is a 16-bit sign-extended value. In the long 
form, the operand is a 32-bit signed value. 

You can force the assembler to use the short (16-bit) form of this in¬ 
struction by using the W operand. You can force the assembler to use the 
long (32-bit) form of this instruction by using the L operand. 

SUBK K, Rd 

Subtract Constant 

Operation: Rd - K -* Rd 

Subtract a 5-bit constant from the contents of the destination register. K 
is an unsigned number in the range 1-32; K^O in the opcode corresponds 
to the value 32. 

SUBXY Rs, Rd 

Subtract Registers in XY Mode 

Operation: RdX - RsX -* RdX 

RdY - RsY -* RdY 

Subtract the X half of Rs from the X half of Rd and subtract the Y half of 
Rs from the Y half of Rd. The destination register contains the result. 

TRAP N 

Software Interrupt 

Operation: PC -*■ -*SP 

ST -*SP 
trap vector N PC 

Perform a software interrupt. N is a trap vector in the range 0-31. The 
return address (the address of the next instruction) and the status register 
are pushed onto the stack, interrupts are disabled, ST is set to 0000001 Oh, 
and the trap vector is loaded into the PC. 

XOR Rs, Rd 

Exclusive-OR Registers 

Operation: Rs XOR Rd -» Rd 

Bitwise-exclusive-OR the contents of the source register with the contents 
of the destination register. 

XORI IL, Rd 

Exclusive-OR Immediate Value 

Operation: ILXOR Rd Rd 

Bitwise-exclusive-OR a 32-bit immediate value with the contents of Rd. 

ZEXT Rd [, F] 

Zero-Extend to Long 

Operation: field in Rd -+ zero-extended field in Rd 

Zero-extend a field in the destination register by setting all the non-field 
bits to 0. 


Key: 

Rs - Source register 

RsX, RdX - X half (16 LSBs) of Rs or Rd 

SAddress - 32-bit source address 

IW - 16-bit (short) immediate value 

Address - 32-bit address (label) 

K ~ 5-bit constant 

PC' - Next instruction 


Rd - Destination register 

RsY, RdY - Y half (16 MSBs) of Rs or Rd 
DAddress - 32-bit destination address 
IL - 32-bit (long) immediate value 

F - Field select; defaults to 0 

F=0 selects FSO and FEO 

F=1 selects FS1 and FE1 
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6.3 Arithmetic, Logical, and Compare Instructions 

The TMS34010 supports a full range of arithmetic, logical, and compare in¬ 
structions. Most of these instructions use register-direct operands; some use 
a combination of immediate and register-direct operands. Some instructions 
have several versions; each uses a different operand format. For example, the 
ADD instruction has several versions: 

• The ADD instruction uses register-direct operands for both the source 
and destination operands. 

• The ADDI instruction uses an immediate source with a destination reg¬ 
ister. 

• The ADDK instruction uses a 5-bit constant as the source operand with 
a destination register. 

• The ADDXY instruction is similar to the ADD instruction - both oper¬ 
ands are register-direct operands - however, the registers contain XY 
values. 

Some instructions that have immediate values as source operands (such as the 
ADDI instruction) have two forms: a short form and a long form. In the short 
form, the source operand is a 16-bit immediate value and the instruction oc¬ 
cupies two words. In the long form, the source operand is a 32-bit immediate 
value and the instruction occupies three words. Each form of the instruction 
has an optional third operand: W for short and L for long. If you don't use the 
W or L operand, the assembler chooses the short or the long form, depending 
on the size of the source operand. Using W or L forces the assembler to use 
the short or long form, respectively. If you use W and the source value is 
greater than 16 bits, the assembler discards all but the 16 LSBs and issues a 
warning message. If you use L and the source value is less than 32 bits, the 
assembler sign-extends the value to 32 bits. 

Some instructions that use immediate operands have only one version. In this 
case, the operand is long (32-bits). 


Note: 

When an instruction's source and destination operands are both regis¬ 
ter-direct operands, the registers must be in the same file. (The MOVE 
Rs, Rd instruction is an exception to this rule.) 


Table 6-1 summarizes the arithmetic, logical, and compare instructions. 
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Table 6-1. Summary of Arithmetic, Logical, and Compare Instructions 


Instruction 

Description 

Instruction 

Description 

ABS Rd 

Store absolute value 

LMO Rs, Rd 

Locate leftmost one 

ADD Rs, Rd 

Add registers 

MODS Rs, Rd 

Modulus (signed) 

ADDC Rs, Rd 

Add registers with carry 

MODU Rs, Rd 

Modulus (unsigned) 

ADDI IW, Rd [,W] 
ADDI IL, Rd [,L] 

Add immediate (short or 
long) 

MPYS Rs, Rd 

Multiply registers (signed) 

ADDK K, Rd 

Add constant 

MPYU Rs, Rd 

Multiply registers (unsigned) 

ADDXY Rs, Rd t 

Add registers in XY mode 

NEG Rd 

Negate register 

AND Rs, Rd 

AND registers 

NEGB Rd 

Negate register with borrow 

ANDI IL, Rd 

AND immediate (long only) 

NOT Rd 

Complement register 

ANDN Rs, Rd 

AND register with comple¬ 
ment 

OR Rs, Rd 

OR registers 

ANDNI IL, Rd 

AND immediate with com¬ 
plement (long only) 

ORI IL, Rd 

OR immediate (long only) 

BTST Rs. Rd t 

BTST K, Rd 

Test register bit (register or 
constant) 

SETC 

Set carry 

CLR Rd 

Clear register 

SEXT Rd [, F] 

Sign extend to long 

CLRC 

Clear carry bit 

SUB Rs,Rd 

Subtract registers 

CMP Rs, Rd 

Compare registers 

SUBB Rs, Rd 

Subtract registers with 
borrow 

CMPI IW,Rd[,\N] 
CM PI IL.Rdl L] 

Compare immediate (short 
or long) 

SUBI IW,Rd[,\N] 
SUBI IL,Rd[, L] 

Subtract immediate (short 
or long) 

CMPXY Rs, Rd t 

Compare registers in XY 
mode 

SUBK K, Rd 

Subtract constant 

DEC Rd 

Decrement register 

SUBXY Rs, Rd t 

Subtract registers in XY 
mode 

DIVS Rs, Rd 

Divide registers (signed) 

XOR Rs, Rd 

Exclusive-OR registers 

DIVU Rs,Rd 

Divide registers (unsigned) 

XORI IL, Rd 

Exclusive-OR immediate 
(long only) 

INC Rd 

Increment register 

ZEXT Rd [, F] 

Zero-extend to long 


t This instruction has a register version and a constant version; both versions use the same mnemonic, 
t Section 6.9 discusses XY instructions. 
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6.4 Move Instructions 

The TMS3401 0 supports a variety of move instructions, allowing you to move 
immediate values into registers, move data between registers, and move data 
between registers and memory. Table 6-2 summarizes the move instructions. 

Table 6-2. Summary of Move Instructions 


Instruction 

Description 

Instruction 

Description 

MMFM Rs [, reg. list] 

Move multiple registers 
from memory 

MOVI IW, Rd [, W] t 
MOVI IL, Rd [, L] 

Move immediate 

MMTM Rs [, reg. list] 

Move multiple registers 
to memory 

MOVK K, Rd 

Move constant 

MOVB t 

Move byte 

MOVX Rs, Rd IT 

Move X half of register 

MOVE § 

Move field 

MOVY Rs, Rd IT 

Move Y half of register 


t Section 6.3 discusses immediate instructions that have both short (16-bit) and long (32-bit) versions. 
$ Nine versions (see Table 6-4) 

§ Eighteen versions (see Table 6-3) 

IT Section 6.9 discusses XY instructions. 


• The MMTM and MMFM instructions use register-direct operands. 
MMTM allows you to save several register values in memory; MMFM 
allows you to retrieve register values from memory. The Rs operand for 
these instructions is a pointer; it contains the address where the register 
values are stored or obtained. The reg. list operand is an optional list of 
registers. It specifies which registers are stored or retrieved, and also 
indicates the storing or retrieval order. Note that Rs and all the registers 
in the list must be in the same register file. If you do not specify a reg¬ 
ister list, the entire register file is stored in or retrieved from memory; the 
register file selected depends on which register file Rs is in. 

• The MOVI and MOVK instructions move immediate values into regis¬ 
ters. The MOVI instruction has two forms; see Section 6.3 (page 6-22) 
for a description of this type of immediate instruction. 

• The MOVX and MOVY instructions move values into the 16 LSBs or 
16 MSBs, respectively, of a register. See Section 6.9 (page 6-33) for a 
discussion of XY instructions. 

• The MOVE instruction supports eighteen combinations of operand for¬ 
mats. There are four basic combinations: 

- Register to register, 

Register to memory, 

- Memory to register, and 

- Memory to memory. 

The MOVE instruction moves a field. A field is a configurable data 
structure that is identified by its starting address and its length. Field 
lengths can range from 1 to 32 bits. A field's memory address points to 
the LSB of the field; the field occupies contiguous bits. A field in a re¬ 
gister is right-justified within the register; the field's LSB coincides with 
the register's LSB. 
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Note that all forms of the MOVE instruction (except MOVE Rs, Rd) have 
an optional F parameter. F selects the field size and field extension for 
the MOVE. If F=0, FSO and FEO determine the field size and extension. 
If F = 1, FS1 and FE1 determine the field size and extension. If you don't 
specify 0 or 1, 0 is used as the default. 

Table 6-3 summarizes the valid combinations of operand formats for the 
MOVE instruction. 

Table 6-3. Summary of Operand Formats for the MOVE Instruction 



Destination 

Source 

Rd 

*Rd 

*Rd+ 

-*Rd 

* Rd{offset) 

@DAddress 

Rs 

V 

V 

V 

V 

V 

V 

*Rs 

V 

V 





*Rs+ 

V 


V 




-*Rs 

V 



V 



*Rs[offset) 

V 


V 


V 


@SAddress 

V 


V 



V 


• The MOVB instruction is a special form of the MOVE instruction; when 
you use MOVB, the field size is restricted to 8 bits. MOVB supports nine 
combinations of operand formats. There are three basic combinations: 

- Register to memory, 

- Memory to register, and 

- Memory to memory. 

(Note that the MOVB instruction does not move data between regis¬ 
ters.) 

The MOVB instruction allows a byte to begin on any bit boundary in 
memory. The byte's memory address points to the LSB of the byte. 
When a byte is moved into a register, the byte's LSB coincides with the 
register's LSB; the byte is sign-extended into the 24 MSBs of the regis¬ 
ter. 

Table 6-4 summarizes the valid combinations of operand formats for the 
MOVB instruction. 


Table 6-4. Summary of Operand Formats for the MOVB Instruction 



Destination 

Source 

Rd 

*Rd 

* Rd{offset) 

@DAddr ess 

Rs 


V 

V 

V 

*Rs 

V 

V 



*Rs(offset) 

V 


V 


@SAddress 

V 



V 
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6.5 Graphics Instructions 

The TMS34010 instruction set supports several fundamental graphics drawing 
operations. Table 6-5 summarizes the graphics instructions. (Note that the 
TMS34010 User's Guide contains detailed descriptions of graphics oper¬ 
ations, pixel blocks, graphics registers, and other related topics.) 

Table 6-5. Summary of Graphics Instructions 


Instruction 

Description 

Instruction 

Description 

CPW Rs, Rd 

Compare point to window 

FILL XY 

t 

Fill array with processed pixels 
(XY) 

CVXYL Rs, Rd t 

Convert XY address to linear 
address 

LINE [0, 1] 

Line draw with XY addressing 

DRAV Rs, Rd 

Draw and advance 

PIXBLT 

t 

Pixel block transfer 

FILL L 

Fill array with processed pixels 
(linear) 

PIXT 

§ 

Pixel transfer 


t Six versions (see Table 6-7) 
t Six versions (see Table 6-6) 

§ Section 6.9 discusses XY instructions. 


• The CPW instruction compares a point to the window limits defined by 
the WSTART and WEND registers. The source operand Rs contains an 
XY address. After the compare operation is performed, bits 5-8 contain 
a code that indicate the point's location with respect to the window 
limits. The entry for the CPW instruction in Section 6.2 shows these 
point codes. 

• The CVXYL instruction converts an XY address to a 32-bit linear ad¬ 
dress. The source register contains the XY address; the linear address is 
put in the destination register. 

• The DRAV instruction draws the pixel value in the COLOR1 register to 
the XY address specified by the destination register. After the pixel is 
drawn, the Y half of Rs is added to the Y half of Rd, and the X half of 
Rs is added to the X half of Rd. 

• The LINE instruction performs the inner loop of Bresenham's line¬ 
drawing algorithm to draw a diagonal, horizontal, or vertical line. The 
optional operand may be a 0 or a 1; this selects one of two algorithms. 
The default for this operand is 0. 

• The FILL instruction fills a two-dimensional pixel array with the value in 
the COLOR1 register. Note that L and XY are not operands ; they are 
part of the instruction mnemonic, identifying the form of the FILL in¬ 
struction. FILL L specifies that the array has a linear starting address; 
FILL XY specifies that the array has an XY starting address. 
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• The PIXT instruction transfers a pixel from one location to another. PIXT 
can transfer a pixel: 

- From a register to memory, 

- From memory to a register, or 

- From memory to memory. 

Table 6-6 summarizes the valid combinations of operand formats for the 
PIXT instruction. Note that all addresses are linear unless the operand 
is suffixed with .XY. 

Table 6-6. Summary of Operand Formats for the PIXT Instruction 



Destination Pixel 

Source 

Pixel 

Rd 

*Rd 

*Rd.X Y 

Rs 


V 

V 

*Rs 

V 

V 


*Rs.X Y 

V 


V 


• The PIXBLT instruction moves a two-dimensional block of pixels from 
one memory location to another. Note that B, L, and XY are not oper¬ 
ands) instead, they identify the source or destination array starting ad¬ 
dresses as binary, linear, or XY addresses. The source and destination 
addresses of the arrays are designated by the SADDR and DADDR reg¬ 
isters, respectively. 

Table 6-7 summarizes the various combinations of pixel block transfers. 


Table 6-7. Summary of Array Types for the PIXBLT Instruction 



| Destination Array 

Source 

Array 

Linear 

XY 

Binary 

V 

V 

Linear 

V 

V 

XY 

V 

V 


The graphics instructions use the B-file registers and several I/O registers as 
implied operands. These registers must be loaded with appropriate values 
before the instruction is executed. The TMS34010 obtains information from 
these registers during instruction execution. Table 6-8 summarizes the implied 
operands that are used by the graphics instructions. The TMS34010 User's 
Guide contains a complete discussion of these registers and describes the 
types of information they should contain. 
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Note that registers B10-B13 are temporary registers for most instructions; for 
the LINE instruction, however, these registers have the following functions: 

BIO: COUNT register B12: INC2 register 
B11: INC1 register B13: PATTRN register 


Table 6-8. Immediate Operands Used by Graphics Instructions 



B File Registers 

I/O Registers 






0 

w 



C 

C 






C 

o 

c 

n 




S 

S 

D 

D 

F 

s 



o 

0 






N 

o 

mm 

P 

P 


A 

p 

A 

P 

F 

T 

w 

D 

L 

L 






T 

N 

mm 

S 

M 

■ 

D 

T 

D 

T 

S 

A 

E 

Y 

O 

O 

B 

B 


B 

B 

R 

V 

n 

1 

A 


D 

c 

D 

C 

E 

R 

N 

D 

R 

R 

mm 

u 


1 

1 

O 

S 

mm 

z 

S 


u 

H 

R 

H 

T 

T 

D 

X 

0 

1 

B 

fl 


3 

4 

L 

P 

El 

E 

K 

CPW Rs, Rd 






q 

Q 














CVXYL Rs, Rd 




B 

B 













a 

B 


DRAV Rs, Rd 




B 

B 


Q 



P 






m 


B 

fl 

fl 

FILL L 



B 





Q 


B 

HI 

m 

m 

m 

m 

Bl 



B 

fl 

FILL XY 



IS 

B 

B 

|Q 

Q 

m 

B 

B 

fl 

m 

m 

m 

§§§ 

B 

B 

fl 

B 

B 

LINE [0, 1] 

H 


ffl 


B 

|Q 

Q 

Q 


B 

H 

Q 

Q 

in 

§§§ 

181 


B 

B 

B 

PIXBLT B, L 

m 

m 

m 

fl 




Q 

B 

B 

II 

B 

B 

m 

m 

181 

B 


B 

B 

PIXBLT B, XY 

m 

m 

in 

B 

B 

Q 

Q 

m 

B 

B 

m 

m 

a 

m 

a 

B 

B 

B 

B 

B 

PIXBLT L, L 

11 

B 

B 

B 




jQ 



m 

m 

m 

a 

m 

B 

181 

B 

B 

fl 

PIXBLT L, XY 

11 

B 

a 

B 

B 

Q 


m 



m 

in 

a 

19 

m 

B 

B 

B 

B 

B 

PIXBLT XY, L 

lul 

B 

s 

B 

B 



Q 



m 

a 

H 

m 

m 

B 

B 

B 

fl 

B 

PIXBLT XY, XY 

m 

B 

Z7; 

B 

B 

|Q 

Q 

HI 



m 

a 

m 

m 

m 

181 

B 

B 

B 

B 

PIXT Rs, *Rd 
















181 



B 

B 

PIXT Rs, *Rd.X Y 




fl 

B 

Q 

Q 









B 


B 

B 

B 

PIXT *Rs, Rd 



















B 

B 

PIXT *Rs, *Rd 












_ 



B 

181 



B 

B 

PIXT *Rs.XY, Rd 




L 

L 












B 


fl 

B 

PIXT *Rs.X Y , *Rd.X Y 


L 


B 

B 

Q 

Q 

_ 






_ 


B 

B 

B 

B 

B 


Key : 


V 

Changed by instruction execution 

t 

Changed as a result of common rectangle func- 

Used; no particular format 


tion with window hit operation (W=1) 

XY 

Register is in XY format 

(D 

CONTROL bits used: PP, W, T 

L 

Register is in linear format 

(2) 

CONTROL bits used: PP, T 

P 

Register is in pixel format 

(3) 

CONTROL bits used: PP, W, T, PBH, PBV 

pat 

Register is in pattern format 

(4) 

CONTROL bits used: PP, T, PBH, PBV 



(5) 

Used when PBV=1 


6-28 





















































Instruction Set - Program Control and Context Switching Instructions 


6.6 Program Control and Context Switching Instructions 

The TMS34010 supports the ability to: 

• Call and return from subroutines, 

• Enable or disable interrupts, 

• Set software interrupts, and 

• Set, save, or restore status information. 

Most of these instructions use register-direct or absolute operands; however, 
several of them have no operands. 

Table 6-9 summarizes these instructions. 

Table 6-9. Summary of Program Control and Context Switching Instructions 


Instruction 

Description 

Instruction 

Description 

CALL Rs 

Call subroutine (indirect) 

POPST 

Pop status register from 
stack 

CALLA Address 

Call subroutine (absolute) 

PUSHST 

Push status register onto 
stack 

CALLR Address 

Call subroutine (relative) 

PUTST 

Copy a register's contents 
into ST 

DINT 

Disable interrupts 

RETI 

Return from interrupt 
(immediate) 

EINT 

Enable interrupts 

RETS [N] 

Return from subroutine 

GETPC Rd 

Get PC into register 

REV Rd 

Store revision number 

GETST Rd 

Get ST into register 

SETF FS, FE [, F] 

Set field size and extension 

NOP 

No operation 

TRAP N 

Software interrupt 
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6.7 Jump Instructions 

The TMS34010 supports both conditional and unconditional jumps. The 
conditional jumps use absolute operands or a combination of register-direct 
and absolute operands. 

Table 6-10. Summary of Jump Instructions 


Instruction 

Description 

Instruction 

Description 

DSJ Rd, Address 

Decrement register and 
skip jump 

JAcc Address 

Jump absolute conditional 

DSJEQ Rd, Address 

Conditionally decrement 
register and skip jump 

JRcc Address t 

Jump relative conditional 

DSJNE Rd, Address 

Conditionally decrement 
register and skip jump 

JUMP Rs 

Jump indirect 

DSJS Rd, Address 

Decrement register and 
skip jump (short) 



t This instruction has a short (±127 words) version and a long (±32K words) version; both versions 
use the same mnemonic. 


• As Table 6-10 shows, there are four DSJ instructions: 

- DSJ and DSJS decrement the contents of a register and jump to 
the specified address if the new contents of Rd do not equal 0. If 
Rd is decremented to 0, then execution continues with the next 
instruction. 

DSJ provides a jump range of -32,768 to +32,767 words; DSJS 
provides a jump range of ±32 words (excluding 0). 

The operation of DSJEQ and DSJNE depends on the value of the 
Z (zero) status bit. 

DSJEQ decrements the contents of Rd when Z=1 and jumps to 
the specified address if the new contents of Rd do not equal 0. If 
Rd is decremented to 0, then execution continues with the next 
instruction. If Z=0, DSJEQ skips the jump and execution contin¬ 
ues with the next instruction. 

DSJNE decrements the contents of Rd when Z=0 and jumps to 
the specified address if the new contents of Rd do not equal 0. If 
Rd is decremented to 0, then execution continues with the next 
instruction. If Z=0, DSJNE skips the jump and execution contin¬ 
ues with the next instruction. 

The address specified for the DSJ instructions is relative; the assembler 
uses this address automatically to calculate a displacement, and then it 
inserts the displacement into the instruction. 

• The JUMP instruction is unconditional. The source register contains 
the address for the jump. 

• The conditional jump instructions, JAcc and JRcc, use the condition 
codes listed Table 6-11. 

The JRcc instruction has a long and a short form. The short form sup¬ 
ports a jump range of ±127 words (excluding 0). The long form sup¬ 
ports a jump range of ±32K words (excluding 0). 
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The 32-bit address specified for the JA cc instruction is absolute; the assembler 
inserts this address into words 2 and 3 of the instruction. The address speci¬ 
fied for the JRcc instructions is relative; the assembler uses this address auto¬ 
matically to calculate a displacement, and then it inserts the displacement into 
the instruction. The short form has an 8-bit displacement that is inserted into 
bits 0-7 of the opcode; the opcode is 1 word long. The long form has 16-bit 
displacement; the opcode is 2 words long, and the displacement occupies the 
entire 16 bits of the second word. 

Table 6-11 lists the condition codes used with the JRcc and JAcc instructions. 
(To use the codes, replace the cc with the appropriate mnemonic code; for 
example, JRUC, JALS, JRYGT, etc.) Before using one of these jump in¬ 
structions, use the CMP, CMPI, or CMPXY instruction; the compare in¬ 
structions set the condition codes for the jump by subtracting a source value 
from a destination value. The first mnemonics code column in Table 6-11 lists 
the codes that can be used for a jump following a CMP or CMPI. The second 
mnemonics code column list codes that can be used for a jump following a 
CMPXY (codes that are preceded with an X can be used with the result of the 
X comparison and codes that are preceded with a Y can be used with the re¬ 
sult of the Y comparison). 

Table 6-11. Condition Codes for JRcc and JAcc Instructions 



Mnemonic 

Code 

Result of Compare 

Status Bits 

Code 

Unconditional 

Compares 

UC 

- 

Unconditional 

don't care 

0000 

Unsigned 

LO (C) 

- 

Dst lower than Src 

C 

BBS! 

Compares 

LS 

YLE 

Dst lower or same as Src 

C + Z 

■SB 111 


HI 

YGT 

Dst higher than Src 

c • z 

■SB 11 


HS (NC) 

- 

Dst higher or same as Src 

c 

1001 


EQ (Z) 

- 

Dst = Src 

z 

1010 


NE (NZ) 

- 

Dst ^ Src 

z 

1011 

Signed 

LT 

XLE 

Dst < Src 

(N • V) + ( N • V) 

0100 

Compares 

LE 

- 

Dst < Src 

(N • V + (N * V) + Z 

0110 


GT 

— 

Dst > Src 

(N • V • Z) + ( N • V • Z) 

0111 


GE 

XGT 

Dst > Src 

(N • V) + (N • V) 

0101 


EQ (Z) 

- 

Dst = Src 

Z 

1010 


NE (NZ) 

- 

Dst ^ Src 

z 

1011 

Compare to 

Z 

YZ 

Result = zero 

z 

0101 

Zero 

NZ 

YNZ 

Result ^ zero 

z 

1011 


P 

- 

Result is positive 

N • Z 

0001 


N 

xz 

Result is negative 

N 

1110 


NN 

XNZ 

Result is nonnegative 

N 

1111 

General 

Z 

YZ 

Result is zero 

Z 

1010 

Arithmetic 

NZ 

YNZ 

Result is nonzero 

z 

1011 


C 

YN 

Carry set on result 

c 

1000 


NC 

YNC 

No carry on result 

c 

1001 


B (C) 

- 

Borrow set on result 

c 

1000 


NB (NC) 

- 

No borrow on result 

c 

1001 


vt 

XN 

Overflow on result 

V 

1100 


NVt 

XNN 

No overflow on result 

V 

1101 


Note: A mnemonic code in parentheses is an alternate code for the preceding code, 
t Also used for window clipping 
+ Logical OR 
j. Logical AND 
Logical NOT 
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6.8 Shift Instructions 

The TMS34010 supports right-shift, left-shift, and circular-shift (rotate) in¬ 
structions. These instructions use register-direct operands or a combination 
of register-direct and immediate operands. 

Table 6-12. Summary of Shift Instructions 


Instruction 

Description 

Instruction 

Description 

RL Rs, Rd 

RL K, Rd 

Rotate left 

SRA Rs, Rd 
SRA K, Rd 

Shift right arithmetic 

SLA Rs, Rd 
SLA K, Rd 

Shift left arithmetic 

SRL Rs, Rd 
SRL K, Rd 

Shift right logical 

SLL Rs, Rd 

SLL K, Rd 

Shift left logical 



These instructions left-rotate, left-shift, or right-shift the contents of the des¬ 
tination register by the value of a 5-bit constant or by the value specified in 
the 5 LSBs of the source register. (Note that the SRA Rs, Rd and SRL Rs, 
Rd use the 2s complement value of the 5 LSBs in Rs.) 

• The RL instruction left-rotates the contents of the destination register 
by. The bits shifted out of the MSB are shifted into the LSB. The C 
(carry) bit is set to the final value shifted out of the MSB. 

• The SLA instruction left shifts the contents of the destination register. 
Os are shifted into the LSBs. The MSBs are shifted out through the C 
(carry) bit so that the C bit is set to the final value shifted out of the 
MSB. If either the N (sign) bit or any of the bits shifted out differ from 
the original sign bit, the V (overflow) bit is set. 

• The SLL instruction left shifts the contents of the destination register. 
Os are shifted into the LSBs. The MSBs are shifted out through the C 
(carry) bit so that the C bit is set to the final value shifted out of the 
MSB. The main difference between SLL and SLA is that SLL does not 
check to see if the sign bit changes. 

• The SRA instruction right shifts the contents of the destination register. 
The value of the sign bit is shifted into the MSBs; this sign-extends the 
value and preserves the original value of the sign bit. The LSBs are 
shifted out through the C (carry) bit so that the C bit is set to the final 
value shifted out of the LSB. 

• The SRL instruction right shifts the contents of the destination register. 
Os are shifted into the MSBs, beginning with bit 31. The LSBs are 
shifted out through the C (carry) bit so that the C bit is set to the final 
value shifted out of the LSB. The main difference between SRL and 
SRA is that SRL does not preserve the original value of the sign bit. 
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6.9 XY Instructions 

The TMS34010 allows you to use XY addresses. This is useful for specifying 
pixel addresses on the screen. Many of the graphics instructions use XY ad¬ 
dressing; the TMS34010 instruction set also supports several other in¬ 
structions that allow you to manipulate XY addresses. 

An XY address is a 32-bit address that is divided into two parts. The 16 LSBs 
of the address are the X half of the address or register; the 16 MSBs of the 
address are the Y half of the address or register. The two parts are treated as 
completely separate values; for example, using the ADDXY instruction, the X 
half does not propagate into the Y half. 

Table 6-13 summarizes the instructions that use XY addresses. 

Table 6-13. Summary of XY Instructions 


Instruction 

Description 

Instruction 

Description 

ADDXY Rs, Rd 

Add registers in XY 

PIXBLT B, XY 

Pixel block transfer 
(binary to XY) 

CPW Rs, Rd 

Compare point to window 

PIXBLT L, XY 

Pixel block transfer 
(linear to XY) 

CMPXY Rs, Rd 

Compare registers in XY 
mode 

PIXBLT XY, L 

Pixel block transfer (XY 
to linear) 

CVXYL Rs, Rd 

Convert XY address to 
linear address 

PIXBLT XY, XY 

Pixel block transfer (XY 
to XY) 

DRAV Rs, Rd 

Draw and advance 

PIXT Rs, *Rd.X Y 

Pixel transfer (register to 
indirect XY) 

FILL XY 

Fill array with processed 
pixels 

PIXT *Rs.XY, Rd 

Pixel transfer (indirect XY 
to register) 

LINE [0,1] 

Line draw with XY 
addressing 

PIXT *Rs.X Y, *Rd.XY 

Pixel transfer (indirect XY 
to indirect XY) 

MOVX Rs, Rd 

Move X half of Rs to X 
half of Rd 

SUBXY Rs, Rd 

Subtract registers in XY 
mode 

MOVY Rs, Rd 

Move Y half of Rs to Y 
half of Rd 



• The PIXBLT and FILL instructions in Table 6-13 use XY source and/or 
destination addresses. 

• The PIXT instructions in Table 6-1 3 use the contents of registers as XY 
addresses. 

• The LINE instruction draws a line along points that are calculated as XY 
addresses. 

• The move instructions in Table 6-13 (MOVX and MOVY) move the X 
or Y half of a source register into the X or Y half of a destination register. 

• The arithmetic and logical instructions in Table 6-13 (ADDXY, SUBXY, 
and CMPXY) add, subtract, or compare the X and Y halves of the regis¬ 
ters separately. 
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Section 7 


Macro Language 


The assembler supports a macro language that allows you to create your own 

"commands." This is especially useful when a program executes a particular 

task several times. The macro language allows you to: 

• Define your own macros 

• Redefine existing opcodes and macros 

• Access macro libraries created with the archiver 

• Manipulate strings within a macro 

• Define conditional and repeatable blocks within a macro 

• Control macro expansion listing 

There are three phases of macro use: 

• Macro definition. Macros must be defined before they can be in¬ 
voked. There are two methods for defining macros: 

1) Macros can be defined in the source file where they are used (or 
in a separate text file that is included with a .copy directive). Since 
macros must be defined before they are called, it is a good practice 
to place all the definitions at the beginning of the file. 

2) Macros can also be defined in a macro library. A macro library 
is a collection of files in archive format, created by the archiver. 
Each member of the archive file (macro library) contains one macro 
definition that corresponds to the name of the member. You can 
access a macro library by using the .mlib directive. Since macros 
must be defined before they can be called, the .mlib directive must 
appear in the source code before any of the macros in the library 
are called. 

• Macro invocation. Once a macro has been defined, the macro name 
can be used as an opcode in a source program. This is referred to as a 
macro call. 

• Macro expansion. When the source program calls a macro, the as¬ 
sembler substitutes the statements within the macro definition for the 
macro call statement. 

This section discusses the following topics: 


Section Page 

7.1 Macro Directives Summary .7-2 

7.2 Macro Libraries .7-3 

7.3 Defining Macros .7-4 

7.4 Macro Parameters . 7-6 

7.5 Conditional Blocks .7-7 

7.6 Repeatable Blocks . 7-8 

7.7 Unique Labels .7-9 
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Macro Language - Macro Directives Summary 


7.1 Macro Directives Summary 


Directive 

Description 

$MACRO 

Macro Definition Directive 

Syntax: macro name $MACRO [parmi][, ... , parm n ] 

The $MACRO directive begins a macro definition. It must be the first statement in 
a macro definition. $MACRO assigns a name to the macro and declares the macro 
parameters. 

The macro name is the name of the macro. A macro name may be 1 to 32 alpha¬ 
numeric characters; it must begin with a letter. The parms are optional parameters. 
When a macro is called, the assembler will associate the first operand in the macro 
call with the first parameter of the macro definition, and so on. 

$IF 

Begin Conditional Block Directive 

Syntax: $IF expression 

The $IF directive begins a conditional block. If the expression evaluates to a non¬ 
zero value, then the code following the $IF directive (up to an $ELSE or $ENDIF 
directive) will be assembled. 

$ELSE 

Alternate Conditional Block Directive 

Syntax: $ELSE 

The $ELSE directive can be used within a conditional block. If the expression in 
an $IF directive evaluates to 0, then code following a corresponding $ELSE directive 
(up to an $ENDIF directive) will be assembled. 

$ENDIF 

Terminate Conditional Block Directive 

Syntax: $ENDIF 

The $ENDIF directive terminates a conditional block. 

$ENDM 

Terminate Macro Definition Directive 

Syntax: $EIMDM 

The $ENDM directive terminates a macro definition. 

$LOOP 

Begin Repeatable Block Directive 

Syntax: $LOOP expression 

The $LOOP directive begins a repeatable block. The expression is evaluated only 
once; the expression should evaluate to a value in the range 0-32767. 

$ENDLOOP 

Terminate Repeatable Block Directive 

Syntax: $ENDLOOP 

The $ENDLOOP directive terminates a repeatable block. 
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7.2 Macro Libraries 

A macro library is a collection of files that contain macro definitions. These 
files, or members, are bound into a single file (called an archive) by the ar¬ 
chiver. Each member of a macro library may contain one macro definition. 
The macro name and the member name must be the same, and the macro 
filename's extension must be .asm. The files in a macro library must be unas¬ 
sembled source files. You can access the macro library by using the .mlib as¬ 
sembler directive: 

.mlib "macro library filename " 

When the assembler encounters an .mlib directive, it opens the library and 
creates a table of its contents. The assembler enters the names of the indi¬ 
vidual members within the library into the opcode table as library entries; this 
redefines any existing opcodes or macros that have the same name. If one of 
these macros is called, the assembler extracts the entry from the library and 
loads it into the macro table. The assembler expands the library entry in the 
same manner as other macros, but it does not place the source code into the 
listing. Only macros that are actually called from the library are extracted, and 
they are only extracted once. 

You can create a macro library with the archiver by simply including the de¬ 
sired files in an archive. A macro library is no different from any other archive, 
except that the assembler expects the macro library to contain macro defi¬ 
nitions. 

The following example creates a macro library called maclib. lib: 

gspar -a maclib.lib macl.asm mac2.asm mac3.asm mac4.asm 

This example adds four macro files (macl.asm, mac2.asm, mac3.asm, and 
mac4. asm) to the library maclib. lib. Note that this could be a new or an 
existing library; if the library already existed, this example would simply ap¬ 
pend the macros to the end of the library. 

Now you can specify maclib. lib to the assembler with an .mlib directive, 
and call any of the macros that it contains: 

.mlib "maclib.lib” 

macl ; Macro call 

The assembler assumes that the files in the archive contain macro definitions 
with the same names as the members. The assembler expects only macro 
definitions in a macro library; putting object code or miscellaneous source files 
into the library may produce undesirable effects. 
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7.3 Defining Macros 

A macro definition is a series of source statements in the following format. 
macname $MACRO [parmj] [ r parm 2 ] ... [,parm n ] 


model statements or macro directives 


$ENDM 

where: 

macname names the macro. It must be placed in the source statement's 
label field. Macro names are significant to 32 characters. The 
assembler places this name in the internal opcode table, replac¬ 
ing any instruction or previous macro definition with the same 
name. 

$MACRO identifies this source statement as the first line of a macro defi¬ 
nition; it must be placed in the opcode field. 

parms are optional parameters which can appear as operands for the 
$MACRO directive. Parameters are not required by all macros. 

model statements 

are instructions or assembler directives that are used each time 
the macro is invoked. 

macro directives 

control the expansion of the macro or manipulate macro param¬ 
eters. 

$ENDM terminates the macro definition. 

The contents of a single macro definition must be contained in the same file. 
Macro definitions cannot be nested, but other directives, instructions, and 
macro calls can be used in a macro definition. The assembler performs only 
limited error checking of macro definitions (during the definition phase), so 
multiple expansions of a macro can produce duplicate error messages. 

When a macro is called, the assembler will substitute the model statements 
and macro directives within the definition for the macro call in the source 
code. Figure 7-1 shows an example of a macro definition, how it could be 
called, and how it would be expanded in the source code. 
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Macro Definition: The following code defines a macro, swap, that has two pa- 


rameters. 

0001 

0002 

0003 

0004 





; 1 

*** swap 

* * * 


swap $MACRO 

R1,R2 ; 

begin 

macro definition 

0005 

xor 

:R1:,:R2: 

model 

statement 

0006 

xor 

:R2s,:Rl: ; 

model 

statement 

0007 

xor 

:R1:,:R2: ; 

model 

statement 

0008 

$END 

; 

end macro definition 


Macro Call: The swap macro is invoked in the source code. 


0009 

0010 

0011 

0012 00000000 


| *** Macro call *** 

swap A0,A1 ; macro call 


Macro Expansion: The assembler substitutes the functional lines of the macro de¬ 
finition for the macro call. The macro parameters are replaced with the operands 
supplied in the macro call. 

0001 00000000 5601 xor A0,A1 

0002 00000010 5620 xor A1,A0 

0003 00000020 5601 xor A0,A1 


Figure 7-1. An Example of a Macro Definition, Call, and Expansion 


When the assembler encounters a macro definition, it places the macro name 
in the opcode table. This redefines any previously defined macro, library entry, 
directive, or instruction mnemonic that has the same name as the encountered 
macro. This allows you to expand the functions of directives and instructions, 
as well as to add new instructions. 


Caution: 

When you specify a macro library with the .mlib directive, the 
assembler places all the entries in the specified library into the 
opcode table - not just the macros that are called. Make sure 
that the macros and instructions you want to use are not rede¬ 
fined by macros in a macro library. 
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7.4 Macro Parameters 

Macros can declare local parameters whose scope is limited to the defining 
macro. These parameters do not conflict with symbols defined outside the 
macro. Only the first eight characters of a parameter name are significant. A 
single macro can declare a maximum of 128 parameters. 

The assembler assigns initial values to macro parameters when the macro is 
called. For example, consider the following macro definition line: 

ADDUP $MACRO val1,val2,sum 

This example defines three parameters (vail, val2, and sum). The assembler 
assigns values to these parameters when it expands the macro; each parameter 
corresponds to an operand in the macro call. 

The value that is assigned to a macro parameter is called a string value. The 
assembler will substitute a parameter's string value into a model statement 
when you enclose the parameter name in colons. Parameters can be used this 
way anywhere in a model statement (as a label, an operand, etc.). 

Figure 7-2 shows a macro that has two parameters. 


0001 



pac_4X8 

$MACRO 

pvalue 



0002 



* Make 

sure these 

are in 

the same 

word 

0003 




. even 




0004 




$LOOP 

8 



0005 




.field 

tpvalue 

4 


0006 




$ENDLOOP 




0007 




$END 




0008 








0009 


0008 

pixval 

. set 

08h 



0010 








0011 

00000000 



pac_4X8 

pixval 



0001 



* Make 

sure these 

are in 

the same 

word 

0002 

00000000 



. even 




0003 

00000000 

0008 


.field 

pixval, 

4 


0004 

00000004 

0008 


.field 

pixval, 

4 


0005 

00000008 

0008 


.field 

pixval, 

4 


0006 

oooooooc 

0008 


.field 

pixval, 

4 


0007 

00000010 

0008 


.field 

pixval, 

4 


0008 

00000014 

0008 


.field 

pixval, 

4 


0009 

00000018 

0008 


.field 

pixval, 

4 


0010 

0000001C 

0008 


.field 

pixval, 

4 



Figure 7-2. An Example of Using Parameter Values 


Thepac-4X8 macro packs 8 4-bit pixels into 32 bits. The parameter pvalue 
is assigned a value that corresponds to the value that is passed when the 
macro is called. 


7-6 





Macro Language - Conditional Blocks 


7.5 Conditional Blocks 

The $IF, $ELSE, and $ENDIF directives are used to construct conditional 
blocks within macro definitions. Conditional blocks can be nested up to ten 
levels deep. Blocks at all nesting levels must always be terminated with an 
$ENDIF. the general format of a conditional block is: 

$1F well- defined expression 

code to assemble if expression is true (* 0) 

$ELSE 

code to assemble if expression is false (= 0) 

$ENDIF 

If the expression in the $IF statement evaluates to a nonzero value, then the 
code that follows it (up to an $ELSE or $ENDIF) will be assembled. If the 
expression evaluates to 0, then the assembler will not assemble the code that 
follows the $IF statement; if an $ELSE directive is present, the assembler will 
assemble the code that follows it (up to the $ENDIF). 

All directives ($IF, $ELSE, and $ENDIF) in a single conditional block must 
appear in the same source module. For example, the $ENDIF cannot appear 
in an included file. A conditional block not terminated by the end of a source 
file (or upon encountering an $ENDM directive) will produce an error. 

In a block of code that is not being assembled, include files and macro defi¬ 
nitions are not scanned. Conditional assembly directives that appear in a 
macro definition are evaluated each time the macro is expanded, not as it is 
defined. 

Figure 7-3 shows an example of a macro with a conditional block. 


0001 



CMPR 

$MACRO 

pl,p2 

0002 




$IF 

:pl: <> :p2: 

0003 




. string 

"not equal" 

0004 




$ELSE 


0005 




.string 

"equal" 

0006 




$ENDIF 


0007 




$ENDM 


0008 






0009 


0001 

syml 

. set 

1 

0010 


0002 

sym2 

. set 

2 

0011 






0012 

00000000 



CMPR 

syml, sym2 

0001 

00000000 

6E 


. string 

"not equal" 


00000008 

6F 





00000010 

74 





00000018 

20 





00000020 

65 





00000028 

71 





00000030 

75 





00000038 

61 





00000040 

6C 





Figure 7-3. An Example of a Conditional Block 
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7.6 Repeatable Blocks 

Repeatable blocks allow a section of code (or a section of a macro definition) 
to be repeatedly expanded. This is particularly useful for table generation. The 
format of a repeatable block is: 

$LOOP expression 

model statements or macro directives 

$ENDLOOP 

The assembler evaluates the expression once when it enters the loop, and then 
it repeats the block expression number of times. The expression can be any 
legal expression or macro expression. 

The same restrictions apply to the declaration of a repeatable block as apply 
to conditional blocks. You can nest up to 10 blocks; you can nest conditional 
blocks within repeatable blocks, and repeatable blocks within conditional 
blocks. The assembler checks to see if blocks are nested properly; if they are 
not, the assembler produces an error message. The following example shows 
improper nesting: 

$LOOP expression 1 

$IF expression 2 

$ENDLOOP 


$ENDIF 

Note that the two blocks overlap rather than nest properly. This is an error, 
and the macro definition will be ignored. 

Figure 7-4 shows an example of a repeatable block. 


0001 



f ill—ar 

$MACRO 

fill—val 

0002 




MOV I 

: fill—val:, A0 

0003 




$LOOP 

4 

0004 




MOVE 

A0, *A1+ 

0005 




$ENDLOOP 


0006 




$END 


0007 






0008 

00000000 


arrayl 

.bss 

W_ar—4, 4*32 

0009 

00000000 

05A1 


MOVE 

©arrayl, A1 


00000010 

00000000+ 




0010 

00000030 



fill-ar 

32h 

0001 

00000030 

09C0 


MOV I 

32h, A0 


00000040 

0032 




0002 

00000050 

9001 


MOVE 

A0, *A1+ 

0003 

00000060 

9001 


MOVE 

A0, *Al+ 

0004 

00000070 

9001 


MOVE 

A0, *Al+ 

0005 

00000080 

9001 


MOVE 

A0, *Al+ 


Figure 7-4. An Example of a Repeatable Block 
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7.7 Unique Labels 

Labels must be unique. If you use an ordinary label in a macro, and the macro 
is expanded more than once, the label in the macro defines the label/symbol 
more than once - this is illegal. The macro language supports a special form 
of label that allows you to create unique labels within macros. To form a 
unique label, simply follow the label name with a question mark ; the syntax 
for a unique label is: 

label? 

Symbols that are defined in this manner can be used like any other symbol; 
you can declare them as global symbols, you can use them in expressions, etc. 

Figure 7-5 shows an example of a macro with unique labels. 


0001 



copyx 

$MACRO 

A,B,length 

0002 



loop? 



0003 




TRAP 

29 

0004 




MOVE 

: A: , * : B : + , 1 

0005 




DSJ 

:length:, loop? 

0006 




$ENDM 


0007 






0008 

00000090 

09C1 


MOV I 

32, Al 


000000A0 

0020 




0009 

000000B0 

09D3 


MOV I 

4, B3 


ooooooco 

0004 




0010 

000000D0 

09D4 


MOV I 

OFFFh, B4 


000000E0 

OFFF 




0011 

000000F0 



copyx 

B3,B4,Al 

0001 

000000F0 


loop? 



0002 

000000F0 

091D 


TRAP 

29 

0003 

00000100 

9274 


MOVE 

B3, *B4+, 1 

0004 

00000110 

3C61 


DSJ 

Al, loop? 

0012 






0013 

00000000 

0770 


SETF 

16, 1, 1 

0014 

00000010 

09D1 


MOV I 

28, B1 


00000020 

001C 




0015 

00000030 

09C1 


MOV I 

32, Al 


00000040 

0020 




0016 

00000050 

09E2 


MOV I 

OCOOOOOOOh, A2 


00000060 

COOOOOOO 




0017 

00000080 

091D 


TRAP 

29 

0018 

00000090 



copyx 

Al,A2,B1 

0001 

00000090 


loop? 



0002 

00000090 

091D 


TRAP 

29 

0003 

000000A0 

9222 


MOVE 

Al, *A2+, 1 

0004 

000000B0 

3C71 


DSJ 

Bl, loop? 


Figure 7-5. An Example of Unique Labels 
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Section 8 


Archiver Description 


The TMS34010 archiver lets you combine several individual files into a single 
file called an archive or a library. Each file within the archive is called a 
member. Once you have created an archive, you can use the archiver to add 
more files to the library, delete or replace existing members, or extract mem¬ 
bers. 

You can build libraries out of any type of files. Both the assembler and the 
linker accept archive libraries as input; the assembler can use libraries that 
contain individual source files, and the linker can use libraries that contain in¬ 
dividual object files. 

One of the most useful applications of the archiver is to build a library of ob¬ 
ject modules. For example, you could write several arithmetic routines, as¬ 
semble them, and then use the archiver to collect the object files into a single, 
logical group. You can then specify an object library as linker input. The linker 
will search through the library and include any members that resolve external 
references. 

You can also use the archiver to build macro libraries. You can create several 
separate source files, each of which contains a single macro, and then use the 
archiver to collect these macros into a single, functional group. The .mlib as¬ 
sembler directive lets you specify the name of a macro library to the assembler; 
during the assembly process, the assembler will search the specified library for 
the macros that you call. Section 7 discusses macros and macro libraries in 
detail. 

This section contains the following topics: 


Section Page 

8.1 Archiver Development Flow ..8-2 

8.2 Invoking the Archiver . 8-3 

8.3 Archiver Examples . 8-4 
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Archiver Description - Development Flow 


8.1 Archiver Development Flow 

Figure 8-1 shows the archiver's role in the assembly language development 
process. Both the assembler and the linker accept libraries as input. 



Figure 8-1. Archiver Development Flow 
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Archiver Description - Invoking the Archiver 


8.2 Invoking the Archiver 

To invoke the archiver, enter: 

gspar [-] command [option] libname [filename / ... filename n ] 

gspar is the command that invokes the archiver; libname names an archive 
library. If you don't specify an extension for libname, the archiver uses the 
default extension .lib. The filenames name individual member files that are 
associated with the library. If you don't specify an extension for a filename, 
the archiver uses the default extension .obj. 

The command tells the archiver how to manipulate the members in the library. 
A command can be preceded by an optional hyphen. You must use one of 
the following commands when you invoke the archiver, but you can only use 
one command per invocation. Valid archiver commands include: 

a adds the specified files to the library. Note that this command does not 
replace an existing member that has the same name as an added file; it 
simply appends new members to the end of the archive. It is possible 
to have several members with the same name in an archive. If you want 
to replace existing members, use the r command. 

d deletes the specified members from the library. If the library contains 
more than one member with a specified name, the archiver deletes the 
first member that has that name. 

r replaces the specified members in the library. If the library contains more 
than one member with a specified name, the archiver replaces the first 
member that has that name. If you don't specify any filenames, the ar¬ 
chiver replaces the library members with files of the same name in the 
current directory. If the specified file is not found in the library, the ar¬ 
chiver adds it instead of replacing it. 

t prints a table of contents of the library. If you specify filenames, only 
those files are listed. If you don't specify any filenames, the archiver lists 
all the members in the specified library. 

x extracts the specified files. If you don't specify any member names, the 
archiver extracts all the members in the library. When the archiver ex¬ 
tracts a member, it simply copies the member into the current directory; 
it doesn't remove it from the library. 

In addition to one of the commands listed above, you can specify the follow¬ 
ing options: 

e tells the archiver not to use the default extension .obj for member names. 

q (quiet) suppresses the banner and status messages. 

s prints a list of the global symbols that are defined in the library. (This 
option is valid only with the -a, -r, and -d commands.) 

v (verbose) provides a file-by-file description of the creation of a new li¬ 
brary from an old library and its constituent members. 
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8.3 Archiver Examples 

Here are some examples of using the archiver. 

• Example 1: 

This example creates a library called function, lib that contains the 
files sine.obj, cos.obj, and flt.obj. 

gspar -a function sine cos fit 

GSP Archiver Version x.xx 87.160 

(c) Copyright 1987, Texas Instruments Inc. 

==> new archive 'function.lib' 

==> building archive 'function.lib' 

Since these examples use the default extensions (.lib for the library 
and .obj for the members), it is not necessary to specify them. 

• Example 2: 

You can print a table of contents of function, lib with the -t option: 

gspar -t function 

GSP Archiver Version x.xx 87.160 

(c) Copyright 1987, Texas Instruments Inc. 


FILE NAME 

SIZE 

DATE 




sine.obj 

248 

Mon 

Nov 

19 

01:25:44 

1984 

cos.obj 

248 

Mon 

Nov 

19 

01:25:44 

1984 

fit.obj 

248 

Mon 

Nov 

19 

01:25:44 

1984 


• Example 3: 

You can explicitly specify extensions if you don't want the archiver to 
use the default extensions; for example: 

gspar -a function.fn sine.asm cos.asm fit.asm 
GSP Archiver Version x.xx 87.160 

(c) Copyright 1987, Texas Instruments Inc. 

==> add 'sine.asm' 

==> add 'cos.asm' 

==> add 'fit.asm' 

==> building archive 'function.fn' 

This creates a library called function.fn that contains the files 
sine, asm, cos. asm, and fit. asm. (-v is the verbose option.) 

• Example 4: 

If you want to add new members to the library, specify: 

gspar -as function tan.obj arctan.obj area.obj 
GSP Archiver Version x.xx 87.160 

(c) Copyright 1987, Texas Instruments Inc. 

==> symbol defined: 'K2' 

==> symbol defined: 'Rossignol' 

==> building archive 'function.lib' 

Since this example doesn't specify an extension for the libname, the ar¬ 
chiver adds the files to the library called function, lib. If func¬ 
tion. lib didn't exist, the archiver would create it. (The -s option tells 
the archiver to list the global symbols that are defined in the library.) 
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• Example 5: 

If you want to modify a member in a library, you can extract it, edit it, 
and replace it. In this example, assume there's a library named mac¬ 
ros, lib that contains the members push, asm, pop. asm, and 
swap. asm. 

gspar -x macros push.asm 

The archiver makes a copy of push, asm and places it in the current di¬ 
rectory; it doesn't remove push, asm from the library, though. Now you 
can edit the extracted file. To replace the copy of push, asm that's in the 
library with the edited copy, enter: 

gspar -r macros push.asm 
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Section 9 


Linker Description 


The TMS34010 linker creates executable modules by combining COFF object 
files. The concept of COFF sections is basic to linker operation; Section 3 
discusses COFF in detail. 

As the linker combines object files, it performs the following tasks: 

• It allocates sections into the target system's configured memory. 

• It relocates symbols and sections to assign them to final addresses. 

• It resolves undefined external references between input files. 

The linker supports a C-like command language that controls memory con¬ 
figuration, output section definition, and address binding. The language pro¬ 
vides two powerful directives, MEMORY and SECTIONS, that allow you to: 

• Define a memory model that conforms to target system memory, 

• Combine object file sections, 

• Allocate sections into specific areas of memory, and 

• Define or redefine global symbols at link time. 

Topics in this section include: 


Section Page 

9.1 Linker Development Flow.9-2 

9.2 Invoking the Linker.9-3 

9.3 Linker Options.9-4 

9.4 Linker Command Files .9-11 

9.5 Object Libraries .9-13 

9.6 The MEMORY Directive .9-14 

9.7 The SECTIONS Directive. 9-16 

9.8 Overlay Pages .9-23 

9.9 Default Allocation .9-26 

9.10Special Section Types (DSECT, COPY, and NOLOAD) .9-28 

9.11 Assigning Symbols at Link Time .9-29 

9.12Creating and Filling Floles .9-32 

9.1 3 Partial Linking . 9-36 

9.14 Linking C Code .9-37 

9.1 5 Linker Example.9-40 
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Linker Description - Development Flow 


9.1 Linker Development Flow 

Figure 9-1 illustrates the linker's role in the assembly language development 
' process. The linker accepts several types of files as input, including object 
files, command files, libraries, and partially linked files. The linker creates an 
executable COFF object module that can be downloaded to one of several 
development tools or executed by a TMS34010. 



Figure 9-1. Linker Development Flow 
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Linker Description - Invoking the Linker 


9.2 Invoking the Linker 

The general syntax for invoking the linker is: 
gsplnk [-options] filename] ... fiiename n 

gsplnk is the command that invokes the linker. The options (discussed in 
Section 9.3) can appear anywhere on the command line or in a linker com¬ 
mand file. The filenames can be object files, linker command files, or archive 
libraries. (The linker can determine whether the input file is an object file or 
an ASCII file that contains linker commands.) The default extension for all 
files is .obj, any other extension must be explicitly specified. The default fi¬ 
lename for the executable output module is a.out. 

There are three methods for invoking the linker: 

• Specify options and filenames on the command line. This example links two 
files, filel.obj, and file2.obj and creates an output module named 

link.out. 

gsplnk filel.obj file2.obj -o link.out 

• Enter the gsplnk command with no filenames or options; the linker will 
prompt for them: 

Command files : 

Object files [.obj] : 

Output files [ ] : 

Options : 

For command files, enter one or more command file names. 

For object files, enter one or more object file names. The default extension is 
.obj. Separate the filenames with spaces or commas; if the last character is a 
comma, the linker will prompt for an additional line of object file names. 

The output file is the name of the linker output module. This overrides any -o 
options entered with any of the other prompts. If there are no -o options and 
you do not answer this prompt, the linker creates an object file with the default 
name a. out. 

The options prompt is for additional options, although you can also enter them 
in a command file. Enter them with hyphens, just as you would on the com¬ 
mand line. 

• Put filenames and options in a linker command file. For example, assume the 
file linker. cmd contains the following lines: 

-o link.out 
filel.obj 
file2.obj 

Now you can invoke the linker from the command line; specify the command 
file name as an input file: gsplnk linker.cmd. 

When you use a command file, you can enter additional options and files on the 
command line. For example, you could enter gsplnk -m link.map link¬ 
er.cmd f ile3 . obj. The linker reads and processes a command file as soon 
as it encounters it on the command line, so it links the files in this order: 
f ilel, f ile2, and f ile3. This example creates an output file called link.out 
and a map file called link. map. 
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9.3 Linker Options 

Linker options control linking operations. Options can be placed on the 
command line or in a command file. Linker options must be preceded by a 
hyphen (-). The order in which options are specified is unimportant except 
for the -I and -i options. Options are separated from arguments (if they have 
them) by an optional space. Table 9-1 summarizes the linker options. 

Table 9-1. Linker Options Summary 


Option 

Description 

-a 

Produce an absolute, executable module. This is the default; if neither -a nor 
-r is specified, the linker acts as if -a is specified. 

-ar 

Produce a relocatable, executable object module. 

-c 

Use linking conventions defined by the ROM autoinitialization model of the C 
compiler. 

-cr 

Use linking conventions defined by the RAM autoinitialization model of the C 
compiler. 

-e global symbol 

Define a global symbol that specifies the primary entry point for the output 
module. 

-f fill value 

Set the default fill value for holes within output sections; fill value is a 4-byte 
constant. 

-h 

Make all global symbols static. 

-i dir 

Alter the library-search algorithm to look in dir before looking in the default lo¬ 
cation. This option must appear before the -1 option. 

-1 filename t 

Name an archive library as the linker input; filename is an archive library name. 

-m filename t 

Produce a map or listing of the input and output sections, including holes, and 
place the listing in filename. 

-0 filename t 

Name the executable output module. The default filename is a.out. 

-q 

Request a quiet run (suppress the banner). 

-r 

Retain relocation entries in the output module. 

-s 

Strip symbol table information and line number entries from the output module. 

-u symbol 

Place an unresolved external symbol into the output module's symbol table. 


t The filename must follow operating system conventions 


9.3.1 Relocation Capability (-a and -r Options) 

One of the tasks the linker performs is relocation. Relocation is the process 
of adjusting all references to a symbol when the symbol's address changes. 
The linker supports two options (-a and -r) that allow you to produce an ab¬ 
solute or a relocatable output module. 

• Producing an Absolute Output Module (-a Option) 

When you use the -a option without the -r option, the linker produces 
an absolute , executable output module. Absolute modules contain no 
relocation information. Executable files: 

- Contain special symbols defined by the linker (Section 9.11.4, 
page 9-31, describes these symbols), 

- Contain an optional header that describes information such as the 
program entry point, and 

- Contain no unresolved references. 
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This example links filel.obj and file2.obj and creates an absolute 
output module called a.out: 

gsplnk -a filel.obj file2.obj 

Note: 

If you do not use the -a or the -r option, the linker acts as if you specified 
-a. 


• Producing a Relocatable Output Module (-r Option) 

When you use the -r option without the -a option, the linker retains re¬ 
location entries in the output module. If the output module will be re¬ 
located (at load time) or relinked (by another linker execution), use -r 
to retain the relocation entries. 

The linker produces an unexecutable file when you use the -r option 
without -a. A file that is not executable does not contain special linker 
symbols or an optional header. The file may contain unresolved refer¬ 
ences, but these references do not prevent creation of an output module. 

This example links filel.obj and f ile2 .obj and creates a relocatable 
output module called a.out: 

gsplnk -r filel.obj file2.obj 

The output file a.out can be relinked with other object files or relocated 
at load time. (Linking a file that will be relinked with other files is called 
partial linking) for more information. Section 9.13, page 9-37.) 

• Producing an Executable Relocatable Output Module (-ar) 

If you invoke the linker with both the -a and the -r options, the linker 
produces an executable , relocatable object module. The output file 
contains the special linker symbols, contains an optional file header, and 
all symbol references are resolved; however, the relocation information 
is retained. 

This example links filel.obj and file2.obj and creates an executa¬ 
ble, relocatable output module called xr. out: 

gsplnk -ar filel.obj file2.obj -o xr.out 

Note that you can string the options together (gsplnk -ar) or you can 
enter them separately (gsplnk -a -r). 

• Relocating or Relinking an Absolute Output Module 

The linker issues a warning message (but continues executing) when it 
encounters a file that contains no relocation or symbol table information. 
Relinking an absolute file can only be successful if each input file con¬ 
tains no information that needs to be relocated (that is, if each file has 
no unresolved references and is bound to the same virtual address that 
it was bound to when the linker created it). 
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9.3.2 C Language Options (-c and -cr Options) 

The -c and -cr options cause the linker to use linking conventions that are 
required by the TMS34010 C compiler. 

• The -c option tells the linker to use the ROM autoinitialization model. 

• The -cr option tells the linker to use the RAM autoinitialization model. 

For more information about linking C code, see section Section 9.14 on page 
9-38. 


9.3.3 Define an Entry Point (-e global symbol Option) 

The memory address that a program begins executing from is called the entry 
point. When a loader loads a program into target memory, the program 
counter must be initialized to the entry point; the PC then points to the be¬ 
ginning of the program. 

The linker assigns one of four possible values to the entry point. These values 
are listed below in the order in which the linker tries to use them. If you use 
one of the first three values, it must be an external symbol in the symbol table. 
Possible entry point values include: 

1) The value specified by the -e option. The syntax is -e global symbol 
where global symbol defines the entry point, and must appear as an ex¬ 
ternal symbol in one of the input files. 

2) The value of symbol -c_intOO (if present). _c-intoo must be the 
entry point if you are linking code produced by the C compiler. 

3) The value of symbol —main (if present). 

4) Zero (default value). 

This example links f ilel. obj and f ile2 . ob j The symbol begin is the entry 
point; begin must be defined as external in f ilel or file2. 

gsplnk -e begin filel.obj file2.obj 

9.3.4 Set Default Fill Value (-f cc Option) 

The -f option fills the holes formed within output sections or initializes unini¬ 
tialized sections when they are combined with initialized sections. This allows 
you to initialize memory areas during link time without reassembling a source 
file. The argument cc is a 4~byte constant (up to eight hexadecimal digits). 
When -f is not used, the default fill value is 0. 

This example fills holes with the hexadecimal value AABBCCDDig: 

gsplnk -f OAABBCCDDh filel.obj file2.obj 
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9.3.5 Make All Global Symbols Static (-h Option) 

The -h option makes all global symbols static. This "hides" symbols, because 
static symbols are not visible to externally linked modules. This allows ex¬ 
ternal symbols with the same name (in different files) to be treated as unique. 

The -h option effectively nullifies all .global assembler directives. All symbols 
become local to the module in which they are defined, so no external refer¬ 
ences are possible. For example, assume filel.obj and file2.obj both 
define global symbols called EXT. By using the -h option, these files can be 
linked without conflict. The symbol EXT defined in filel.obj is treated se¬ 
parately from the symbol EXT defined in f ile2 . ob j. 

gsplnk -h filel.obj file2.obj 

9.3.6 Alter the Library Search Algorithm (-i dir Option/C—DIR) 

Usually when you want to specify a library as linker input, you simply enter the 
library name as you would any other input filename; the linker looks for the 
library in the current directory. For example, suppose the current directory 
contains the library object, lib. Assume that this library defines symbols 
that are referenced in the file filel.obj. This is how you link the files: 

gsplnk filel.obj object.lib 

If you want to use a library that is not in the current directory, use the -I 
(lowercase "L") linker option. The syntax for this option is -I filename. The 
filename is the name of an archive library; the space between the -I and the 
filename is optional. 

You can augment the linker's directory search algorithm by using the -i linker 
option or the environment variable. The linker searches for object libraries in 
the following order: 

1) It searches directories named with the -i linker option. 

2) It searches directories named with the environment variable C—DIR. 

3) If C—DIR is not set, it searches directories named with the assembler's 
environment variable. A—DIR. 

4) It searches the current directory. 

9.3.6.1 -i Linker Option 

The -i linker option names an alternate directory that contains object libraries. 
The syntax for this option is -i dir dir names a directory that contains object 
libraries; the space between -i and the directory name is optional. When the 
linker is searching for object libraries named with the -I option, it searches 
through directories named with -i first. Each -i option specifies only one di¬ 
rectory, but you can use several -i options per invocation. When you use the 
-i option to name an alternate directory, it must precede the -I option on the 
command line or in a command file. 

As an example, assume that two archive libraries called r. lib and lib2 . lib 
reside in directories called: 

• \ld and \ld2, respectively (PC/MS-DOS), 

• [Id] and [ld2], respectively (VAX/VMS), or 

• /Id and /ld2, respectively (VAX/UNIX and System V). 

You can use both libraries during a link: 
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DOS: 

VMS: 

UNIX: 


gsplnk fl.obj f2.obj -i\ld 
gsplnk fl.obj f2.obj -i[ld] 
gsplnk fl.obj f2.obj -i/ld 


-i\ld2 -lr.lib -llib2.1ib 
-i[ld2] -lr.lib -llib2.1ib 
-i/ld2 -lr.lib -llib2.1ib 


9.3.6.2 Environment Variable (C—DIR) 

An environment variable is a system symbol that you define and assign a string 
to. The linker uses an environment variable named C—DIR to name alternate 
directories that contain object libraries. The command for assigning the envi¬ 
ronment variable is: 

DOS: set C—D\R=pathname;another pathname ... 

VMS: assign C—DIR " pathname;another pathname ... " 

UNIX: setenv C— DIR "pathname;another pathname ... " 

The pathnames are directories that contain object libraries. Use the -I option 
on the command line or in a command file to tell the linker which libraries to 
search for. 

As an example, assume that two archive libraries called r. lib and lib2. lib 
reside in directories called: 


• \ld and \ld2, respectively (PC/MS-DOS), 

• [Id] and [ld2], respectively (VAX/VMS), or 

• /Id and /ld2, respectively (VAX/UNIX and System V). 


You can use both libraries during a link; set the environment variable first: 


DOS: set 

gsplnk 

VMS: assign 
gsplnk 

UNIX: setenv 
gsplnk 


C—DIR=\ldir;\ldir2 
fl.obj f2.obj -lr.lib 

C-DIR M /ldir;ldir2" 
fl.obj f2.obj -lr.lib 

C-DIR "/ldir;ldir2" 
fl.obj f2.obj -lr.lib 


-llib2.lib 


-llib2.lib 


-llib2.lib 


Note that the environment variable remains set until you reboot the system or 
reset the variable by entering: 


DOS: set C_DIR= 

VMS: deassign C—DIR 

UNIX: setenv C—DIR 


The assembler uses an environment variable named A—DIR to name alternate 
directories that contain copy/include files or macro libraries. IF C—DIR is not 
set, the linker will search for object libraries in the directories named with 
A-DIR. 

Section 9.5 (page 9-13) contains more information about object libraries. 
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9.3.7 Create a Map File (-m filename Option) 

The -m option creates a link map listing and puts it in filename. This map 
describes: 

• Memory configuration, 

• Input and output section allocation, and 

• The addresses of external symbols after they have been relocated. 

The map file contains the name of the output module, the entry point, and 
may also contain up to three tables: 

• A table showing the new memory configuration, if any nondefault me¬ 
mory is specified. 

• A table showing the linked addresses of each output section and the 
input sections which comprise the output sections. 

• A table showing each external symbol and its address. This table has 
two columns: the left column contains the symbols sorted by name, the 
right column contains the symbols sorted by address. 

This example links filel.obj and file2.obj and creates a map file called 
map.out: 

gsplnk filel.obj file2.obj -m map.out 

See Section 9.1 5 (page 9-41) for an example of a map file. 

9.3.8 Name an Output Module ( o filename Option) 

The linker always creates an executable output module. If you do not specify 
a filename for the output module, the linker gives it the default name a.out. 
If you want to assign a different name to the output module, use the -o option. 
The filename is the new output module name. 

This example links filel.obj and file2.obj and creates an output module 
called run. out: 

gsplnk —o run.out filel.obj file2.obj 


9.3.9 Specify a Quiet Run (-q Option) 

The -q option suppresses the linker's banner when -q is the first option on the 
command line or in a command file. This option is useful for batch operation. 
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9.3.10 Strip Symbolic Information (-s Option) 

The -s option creates a smaller output module by omitting symbol table in¬ 
formation and line number entries. The -s option is useful for production ap¬ 
plications, when you must create the smallest possible output module. 

This example links f ilel. obj and f ile2. obj and creates an output module, 
stripped of line numbers and symbol table information, named nolink.out: 

gsplnk -o nolink.out -s filel.obj file2.obj 

Note that using the -s option limits later use of a symbolic debugger, and may 
prevent a file from being relinked. 

9.3.11 Introduce an Unresolved Symbol (-u symbol Option) 

The -u option introduces an unresolved symbol into the linker's symbol table. 
This forces the linker to search through a library and include the member that 
defines the symbol. Note that the linker must encounter the -u option before 
it links in the member that defines the symbol. 

For example, suppose a library named rts.lib contains a member that de¬ 
fines a symbol symtab; none of the files you are linking reference symtab. 
However, suppose you plan to relink the output module, and you would like 
to include the module that defines symtab in this link. Using the -u option 
as shown below forces the linker to search rts. lib for the member that de¬ 
fines symtab and to link in the member. 

gsplnk -u symtab filel.obj file2.obj rts.lib 

If you do not use -u, this member is not included since there is no explicit re¬ 
ference to it in f ilel. obj or f ile2 . obj. 
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9.4 Linker Command Files 

Linker command files allow you to put linking information in a file; this is 
useful when you often invoke the linker with the same information. Linker 
command files are also useful because they allow you to use the MEMORY 
and SECTIONS directives to customize your application. You must use these 
directives in a command file; you cannot use them on the command line. 
Command files are ASCII files that contain one or more of the following: 

• Input file names, which specify object files, object libraries, or other 
command files. (If a command file calls another command file as input, 
this statement must be the last statement in the calling command file. 
The linker does not return from the called command file.) 

• Linker options, which can be used in the command file in the same 
manner that they are used on the command line. 

• The MEMORY and SECTIONS linker directives. The MEMORY directive 
defines the target memory configuration. The SECTIONS directive con¬ 
trols how sections are built and allocated. 

• Assignment statements, which define and assign values to global sym¬ 
bols. 

To invoke the linker with a command file, enter the gsplnk command and 
follow it with the name of the command file: 

gsplnk command file name 

The linker processes input files in the order that it encounters them. If the 
linker recognizes a file as an object file, it links it. Otherwise, it assumes a file 
is a command file, and begins reading and processing commands from it. 

Figure 9-2 shows a sample linker command file called link. cmd. 


/*******************************************************/ 
/* Sample Linker Command File */ 

/*******************************************************/ 

a. obj /* First input filename */ 

b. obj /* Second input filename */ 

-o prog.out /* Option to specify output file */ 

-m prog.map /* Option to specify map file */ 


Figure 9-2. An Example of a Linker Command File 


The sample file in Figure 9-2 contains only filenames and options. (Note that 
you can place comments in a command file by delimiting them with /* and */.) 
To invoke the linker using this command file, enter: 

gsplnk link.cmd 

You can place other parameters on the command line when you use a com¬ 
mand file: 

gsplnk -r link.cmd c.obj d.obj 
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The linker processes the command file as soon as it encounters it, so a.obj 
and b.obj are linked into the output module before c.obj and d.obj. 

You can specify multiple command files for a single link. If, for example, you 
have a file called names. 1st that contains filenames and another file called 
dir.cmd that contains linker directives, you could enter: 

gsplnk names.1st dir.cmd 

One command file can also call another command file; this type of nesting is 
limited to 1 6 levels. If a command file names another command file as input, 
this statement must be the last statement in the calling command file. 

Blanks and blank lines that appear in a command file are insignificant except 
as delimiters. This applies to the format of linker directives in a command file, 
also. Figure 9-3 shows a sample command file that contains linker directives. 
(Linker directive formats are discussed in later sections.) 


/*******************************************************/ 
/* Sample Linker Command File with Directives */ 

/*******************************************************/ 
a.obj b.obj c.obj /* Input filenames */ 

-o prog.out -m prog.map /* Options */ 


MEMORY 

{ 

RAM: origin = lOOh , 
ROM: origin = OlOOOh , 


/* MEMORY directive */ 

length = OlOOh 
length = OlOOh 


SECTIONS /* SECTIONS directive */ 

{ 

.text: {} > ROM 
.data: {} > ROM 
.bss: {} > RAM 

} 


Figure 9-3. An Example of a Command File with Linker Directives 


The following names are reserved as keywords for linker directives. Do not 
use them as symbol or section names in a command file. 


align 

1 (lowercase "L") 

origin 

ALIGN 

len 

ORIGIN 

block 

length 

page 

BLOCK 

LENGTH 

PAGE 

COPY 

MEMORY 

range 

DSECT 

NOLOAD 

SECTIONS 

group 

0 

spare 

GROUP 

org 
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9.5 Object Libraries 

An archive library is a partitioned file that contains complete object files as 
members. Usually, a group of related modules are collected together into a 
library. When you specify an object library as linker input, the linker links in 
any members that define existing unresolved symbol references. You can use 
the TMS34010 archiver to build and maintain libraries (see Section 8). 

Using object libraries can reduce link time and can reduce the size of the 
executable module. If a normal object file that contains a function is specified 
at link time, it is linked whether it is used or not; however, if that same function 
is placed in a library, it is only included if it is referenced. 

The order in which you specify libraries as input is important because the 
linker includes only those members that resolve symbols that are undefined 
when the library is searched. The same library can be specified as often as 
necessary; it is searched each time it is included. A library contains a table that 
lists all external symbols defined in the library; the linker searches through the 
table until it determines it cannot use the library to resolve any more refer¬ 
ences. 

This example links several files and libraries. Assume the following: 

• Input files f l.obj and f2.obj both reference an external function 
named clrscr. 

• Input file fl. obj references the symbol origin. 

• Input file f 2 . obj references the symbol fillclr. 

• Library libc. lib, member 0, contains a definition of origin. 

• Library liba. lib, member 3, contains a definition of fillclr. 

• Both libraries have a member 1 that defines clrscr. 

If you enter: gsplnk f l.obj liba. lib f2.obj libc. lib 

then: 

• Member 1 of liba. lib satisfies both references to clrscr, because the 
library is searched and clrscr is defined before f2 . obj references it. 

• Member 0 of liba. lib satisfies the reference to origin. 

• Member 3 of libc. lib satisfies the reference to fillclr. 

• Both liba. lib and libc. lib are in the current directory. 

If, however, you enter: gsplnk fl.obj f2.obj libc.lib liba.lib 

then the references to clrscr are satisfied by member 1 of libc. lib. If none 
of the linked files reference symbols defined in a library, you can use the -u 
linker option to force the linker to include a library member. The next example 
creates an undefined symbol routl in the linker's global symbol table: 

gsplnk -u routl libc.lib 

If any members of libc. lib define routl, then the linker includes those 
members. Note that it is not possible to control the allocation of individual 
library members; members are allocated according to the SECTIONS directive 
default allocation algorithm. 

Section 9.3.6 (page 9-7) describes methods for specifying directories that 
contain object libraries. 


9-13 





Linker Description - The MEMORY Directive 


9.6 The MEMORY Directive 

The linker determines where output sections should be allocated into memory; 
the linker must have a model of target memory to accomplish this task. The 
MEMORY directive allows you to specify a model of target memory, so you 
can define the types of memory your system contains and the address ranges 
they occupy. The linker maintains the model as it allocates output sections, 
and uses the model to determine which locations in the target system can be 
used for the linked program. 

The memory configurations of TMS34010 systems differ from application to 
application. The MEMORY directive allows you to specify a variety of con¬ 
figurations. After you use the MEMORY directive to define a memory model, 
you can use the SECTIONS directive to allocate output sections into defined 
memory. 

9.6.1 Default Memory Model 

If you do not use the MEMORY directive, the linker uses a default memory 
model which assumes that the full 32-bit address space (2 32 locations) is 
present in the system and available for use. For more information about this 
default model, see Section 9.9 on page 9-26. 

9.6.2 MEMORY Directive Syntax 

The MEMORY directive identifies ranges of memory that are physically present 
in the target system and can be used by a program. Each memory range has 
a name, a starting address, and a length . 

When you use the MEMORY directive, be sure to identify all the memory 
ranges that are available to load object code into. Memory that is defined by 
the MEMORY directive is configured memory; any memory that you do not 
explicitly account for with the MEMORY directive is unconfigured 
memory. (Note that under the default memory model, the entire address 
space is configured.) The linker can only use configured memory; it cannot 
place any part of a program into unconfigured memory. 

The MEMORY directive is specified in a command file by the word MEMORY 
(uppercase), followed by a list of memory range specifications enclosed in 
braces. The MEMORY directive in Figure 9-4 defines a system that has 4K 
of ROM at address 0 and 8K of RAM at address OEOOOh. 


MEMORY-^ 

directive 


/it********************************************/ 

/* Sample command file with MEMORY directive */ 

/*********************************************/ 
filel.obj file2.obj /* Input files */ 
-o prog.out /* Options */ 


-MEMORY 

{ 


-origins 


i-ROM : l-origin = Oh , length 

[-RAM : l-origin = OEOOOh , length 

-memory range names 


1000h-i 

2000h-4 


■lengths 


Figure 9-4. An Example of the MEMORY Directive 
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The general syntax for the MEMORY directive is: 

MEMORY 

{ 

name 1 [(attr)] : origin = constant, length = constant 
name 1 [(attr)] : origin = constant, length = constant 

} 

(Boldfaced items should be entered as shown.) 

name names a memory range. A memory name may be 1 to 8 characters; 

valid characters include A-Z, a-z, $, and —. The names have no 
significance to the program; they simply identify memory ranges for 
the linker. Memory range names are internal to the linker and are not 
retained in the output file or in the symbol table. 

attr specifies 1 to 4 optional attributes associated with the named range. 
Valid attributes include: R (readable memory), W (writable memory), 
X (executable memory), and I (initializable memory). The attribute 
list must be enclosed in parentheses. If you do not specify any attri¬ 
butes for a memory range, then the range has all four attributes . All 
memory in the default model has all four attributes. The following 
example specifies a memory range with the R and X attributes: 

MEMORY 

{ ROM (RX) : origin = 0 , length = OlOOOh} 

origin specifies the starting address of a memory range. It may be entered 
as origin, org, or o. The value, specified in bits, is a long integer 
constant, and may be decimal, octal, or hexadecimal. The comma 
that follows the origin specification is optional. 

length specifies the length of a memory range. It may be entered as length, 
ten, or /. The value, specified in bits, is a long integer constant, and 
may be decimal, octal, or hexadecimal. 

Figure 9-5 illustrates the memory map defined by Figure 9-4. 


• -'.1 

OOOOOOOOh 

ROM 

OOOOOFFOh 

mmm 

^unconfigured^ 

W//////M 

00001OOOh 

-:i 

OOOOEOOOh 

RAM 

’ / . 

OOOOFFFFOh 

^unc^^igured 1 

W/M//M 

0001OOOOOh 

OFFFFFFFOh 


Figure 9-5. Memory Map Defined in Figure 9-4 
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9.7 The SECTIONS Directive 

The SECTIONS directive tells the linker how to combine sections from input 
files into sections in the output module and where to place the output sections 
in memory. In summary, the SECTIONS directive: 

• Describes how input sections will be combined into output sections. 

• Defines output sections in the executable program. 

• Specifies where output sections will be placed in memory (in relation to 
each other and to the entire memory space), and 

• Permits renaming of output sections. 

9.7.1 Default Sections Configuration 

If you do not specify a SECTIONS directive, the linker uses a default algorithm 
for combining and allocating the sections. Section 9.9 (page 9-26) describes 
this algorithm in detail. 

9.7.2 SECTIONS Directive Syntax 

The SECTIONS directive is specified in a command file by the word SEC¬ 
TIONS (uppercase), followed by a list of output section specifications en¬ 
closed in braces. Figure 9-6 contains an example of the SECTIONS directive. 


SECTIONS 

directive 


section 

specifications 


Figure 9-6. An Example of the SECTIONS Directive 

The general syntax for the SECTIONS directive is: 

SECTIONS 

{ 

section specification 1 
section specification 2 


section specification n 

} 



9-16 





Linker Description - The SECTIONS Directive 


Each section specification defines an output section. (An output section is a 

section in the output file.) The syntax for a section specification is: 

name [binding or align(/7) ] : 

{ 

input sections 
assignments 

} [ - fill value] [ > named memory] 

(Boldfaced portions should be entered as shown.) 

name names the section in the output file. Only the first 8 characters 

of output section names are significant. 

binding is optional, and assigns the section to a specific physical ad¬ 
dress in the target memory. Section 9.7.4 (page 9-20) dis¬ 
cusses assigning an address to an output section. 

align(n) is optional, and specifies that the section should be aligned on 
an n-bit boundary (the actual address is determined by the 
linker). Section 9.7.4 (page 9-20) discusses aligning an out¬ 
put section. 

input 

sections is a list of input sections that are combined to form the output 
section. The list is enclosed in braces; if the braces are empty 
(no input sections are specified), the linker includes all input 
sections with the same name as the output section. Section 
9.7.3 (page 9-1 8) discusses specifying input sections in detail. 

assignment is optional, and defines the value of symbols at link time or 
creates uninitialized spaces (called holes) between input sec¬ 
tions within the output section. Section 9.11 (page 9-29) 
discusses linker assignment statements, and Section 9.12 
(page 9-32) contains more information about holes. 

fill value is optional, and specifies a value for filling holes in the section. 

See Section 9.12 (page 9-32) for more information about fill 
values for holes. 

>named 

memory is optional, and specifies that an output section should be al¬ 
located into a memory range that was named by the MEMORY 
directive. Section 9.7.4 (page 9-20) discusses named memory. 

Figure 9-7 shows how the sections in Figure 9-6 (page 9-16) are allocated. 

Figure 9-6 defines four output sections, .text, .data, init, and .bss: 

• The .text output section is made up of the .text sections from f ilel. ob j 
and f ile2. ob j. Notice that the braces ({ }) are empty in this section 
specification; this tells the linker to include all the .text input sections. 

An address was specified for the .text section (this is called binding ), so 
the .text output section will begin at address OlOOOh in the target me¬ 
mory. 

• The .data output section contains the .data section from f ilel .obj. 

• The Init section is composed of the init (named) section in f ilel. obj 
and the .data section in file2.obj. 
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• The .bss output section is composed of the .bss sections from 
f ilel.obj and f ile2.obj. This output section will be aligned on the 
next available 16-bit boundary. 

Figure 9-7 shows how the sections in Figure 9-6 are allocated. 


filet 

text 


file 2 
.text 

fUel 


.data 




jfift ;; 




.data 


im 


T bse : . • 


m2 ■ ■ ■ . 


: : rtm 



.text output section; 
must start at 
address OlOOOh 


.data output section 


.init output section 


.bss output section; 
must be aligned on 
a 16 -bit boundary 


Figure 9-7. Section Allocation Defined by Figure 9-6 


9.7.3 Specifying Input Sections 

An input section specification identifies the sections from input files that are 
combined to form an output section. The linker combines input sections by 
concatenating them in the order in which they are specified. The size of an 
output section is the sum of the sizes of the input sections that make up the 
output section. 

Figure 9-8 shows the most common type of section specification; note that 
no input sections are listed. 


SECTIONS 

{ 



. text 

: { 

} 

. data 

: ( 

} 

.bss 

} 

: { 

} 


Figure 9-8. The Most Common Method of Specifying Section 

Contents 


In the example shown in Figure 9-8, the linker takes all the .text sections from 
the input files and combines them into the .text output section. It concat¬ 
enates them in the order in which it encountered them in the input files. The 
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linker performs similar operations with the .data and .bss sections. You can 
use this type of specification for any output section. 

You can explicitly specify the input sections that form an output section. Each 
input section is identified by its filename and section name: 

SECTIONS 
{ 

.text : 

{ 

f1.obj(.text) 
f2.obj(seel) 
f3.obj 

f4.obj(.text, sec2) 

} 

Note that it is not necessary for input sections to have the same name as each 
other, or of the output section they become part of. If a file is listed with no 
sections, all of its sections are included in the output section. If there are any 
additional input sections that have the same name as the output section, but 
are not explicitly specified by the SECTIONS directive, they are automatically 
linked in at the end of the output section. For example, if the linker found 
more .text sections in the preceding example, and these .text sections were 
not specified anywhere in the SECTIONS directive, then the linker would 
concatenate these extra sections after f4. obj (sec2). 

The specifications in Figure 9-8 are actually a shorthand method for the fol¬ 
lowing: 

SECTIONS 
{ 

.text 
. data 
.bss 

} 

The *( .text) means the unallocated .text sections from all the input files 
This format is useful when: 

• You want the output section to contain all input sections that have a 
certain name, but the output section name is different from the input 
sections' name. 

• You want the linker to allocate the input section before it processes ad¬ 
ditional input sections or commands within the braces. 

Here's an example that uses this method: 

SECTIONS 

{ 

.text: { 

abc.obj(xqt) 

*(.text) 

} 

.data : { 

*(.data) 
fil.obj(table) 

} 

In this example, the .text output section contains a named section xqt from 
file abc.obj, followed by all the .text input sections. The .data section con- 


{ *(.text) } 
{ *(.data) } 
{ *(.bss) } 


/* Build .text output section */ 

/* Link .text section from fl.obj */ 
/* Link seel section from f2.obj */ 
/* Link ALL sections from f3.obj */ 
/* Link .text and sec2 from f4.obj */ 
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tains all the .data input sections, followed by a named section table from file 
f il.obj. Note that this method includes all the unallocated sections. For 
example, if one of the .text input sections was already included in another 
output section when the linker encountered *( .text), the linker could not 
include that first .text input section in the second output section. 

9.7.4 Specifying the Address of Output Sections (Allocation) 

After you specify the contents of each output section, you must specify the 
physical location in target memory where the output section will be loaded. 
Each section has an address field in its section header that tells a loader where 
the section should go. The process of calculating the addresses of the output 
sections is called allocation. 

If you do not specify an explicit starting address for an output section, the 
linker uses a default algorithm to allocate the section. Generally, the linker 
puts sections where ever they fit into configured memory. 

You can override this default allocation by telling the linker where the section 
should be loaded. You can use three methods to control section allocation: 

• Binding 

You can supply a specific address for an output section by following the 
section name with the address: 

.text OlOOOh : { ... } 

This example specifies that the .text section must begin at location 
lOOOh. The binding address must be a 32-bit constant. 

Output sections can be bound anywhere in configured memory (as¬ 
suming there is enough space), but they cannot overlap. If there is not 
enough space to bind a section to a specified address, the linker issues 
an error message. 

Note that you cannot use the binding method if you use alignment or 
named memory. If you try to do this, the linker issues an error message. 

• Alignment 

You can tell the linker to place an output section at an address that falls 
on an n-bit boundary, where n is a power of 2. For example, 

SECTIONS 

{ 

.data ALIGN(32) :{...} 

} 

In this example, the .data output section is not bound to a specific ad¬ 
dress; it is linked at the next available address in configured memory that 
is a multiple of 32 bits. 

The assembler also supports a method for specifying alignment. The 
.align assembler directive aligns code or data on a 32-word (cache) 
boundary. When you use .align, the assembler sets a flag that tells the 
linker to align the entire section. This ensures that all the alignments 
within the section are correct when the section is relocated. 
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• Named Memory 

You can allocate a section into a memory range that is defined by the 
MEMORY directive. This example names ranges and links sections into 
them: 


MEMORY 

{ 

ROM (RIX) : 




origin = 

Oh, 

length = lOOOh 

RAM (RWIX): 

} 

SECTIONS 

{ 

.text : 

origin = 

3000h, 

length = lOOOh 

{ . 

... } > 

ROM 

.data ALIGN (64) : { , 

... } > 

RAM 

.bss : 

} 

{ . 

. . . } > 

RAM 


In this example, the linker places .text into the area called ROM, between 
locations Oh and OFFFh. The .data and .bss sections are allocate into the 
named memory range ram. It is possible to align a section within named 
memory; the .data section is aligned on a 64-bit boundary within ram. 

Similarly, you can specify link a section into an area of memory that has 
particular attributes. To do this, specify a set of attributes (enclosed in 
parentheses) instead of a memory name. Assuming you used the same 
MEMORY directive declaration, you can specify: 

/**************************************************/ 

/** .text --> executable memory **/ 

/** .data --> readable or initializable memory **/ 

/** .bss --> readable or writable memory **/ 

/**************************************************/ 

SECTIONS 

{ 

.text: {...} > (X) 

.data: { . . .} > (RI) 

.bss : {...} > (RW) 

} 

In this example, the .text section can be linked into either the ROM or 
ram area, since both are declared with the X attribute. The .data section 
can also go into either ROM or ram, since both have the R and I attri¬ 
butes. The .bss section, however, must go into the RAM area, because 
only ram has the W attribute. 

You cannot control where in a named memory range a section is allo¬ 
cated, although the linker uses lower memory addresses first and avoids 
fragmentation when possible. In the preceding examples, assuming no 
other sections were bound to addresses that would interfere with this 
allocation process, the .text section would start at address 0. If a section 
must start on a specific address, use binding instead of named memory. 
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9.7.5 Grouping Output Sections Together 

The SECTIONS directive has a GROUP option that forces several output sec¬ 
tions to be allocated contiguously. For example, assume that is a section 
named term-rec contains a termination record for a table in the .data section. 
You can force the linker to allocate .data and term_rec together: 

SECTIONS 
{ 

.text : { } 

.bss : { } 

GROUP lOOOh : 

{ 

.data : { } 

ternurec : { } 

} 

} 

You can use binding, alignment, or named memory to allocate a GROUP of 
output sections in the same manner that you can allocate a single output 
section. In the preceding example, the GROUP is bound to address lOOOh. 
This means that .data is allocated at lOOOh, and term-rec follows it in me¬ 
mory. You can also use alignment and named memory with the GROUP op¬ 
tion. 


/* Normal output section */ 
/* Normal output section */ 
/* Specify a group of sections */ 

/* First section in the group */ 
/* Follows .data in memory */ 


Note: 

When you use the GROUP option, binding, alignment, or allocation into 
named memory can be specified for the group only . You cannot specify 
addresses for sections within a group. 
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9.8 Overlay Pages 

Some target systems use an overlay memory configuration, where all or part 
of the memory space is overlayed by shadow memory. A system can map 
different banks of physical memory in and out of a a single address range in 
response to hardware select signals. In this situation, multiple areas of phys¬ 
ical memory overlay each other at one address space. You may want the linker 
to load various output sections into each of these areas, or into areas that are 
not mapped at load time. 

The linker supports this feature by providing overlay pages , allowing you to 
define a memory model with multiple address spaces. To the linker, each 
possible overlay configuration represents a separate address space. Each ad¬ 
dress range is treated as a separate page, and must be configured separately 
with the MEMORY directive. You can then use the SECTIONS directive to 
specify map sections into various pages. 

9.8.1 Using the MEMORY Directive to Define Overlay Pages 

Each separately configured address space is called a page. To the linker, each 
page represents a completely separate memory that has the full 32-bit range 
of addressable locations. This allows you to link two or more sections at the 
same (or overlapping) addresses if they are on different pages. 

Pages are numbered sequentially, beginning with 0. PAGE 0 represents the 
normal address space of the TMS34010. The default memory model resides 
entirely on PAGE 0. If a memory range is specified without a page number, 
the linker allocates it into PAGE 0. This allows you to ignore the page feature 
for normal cases; everything can be linked in PAGE 0 with no overlays. 

For example, assume that your system can select between three 4K banks of 
physical memory to map into the address space from lOOOh to 2000h. Al¬ 
though only one bank can be selected at a time, you can initialize each bank 
with different data. Assume that three output sections called secto, sectl, 
and sect2 must be linked into the three banks of memory. Figure 9-9 shows 
the MEMORY directive that defines this configuration. Figure 9-10 (page 
9-24) illustrates this configuration; it shows each available block of physical 
memory in the system and the section that must be loaded into it. 


/**************************************************/ 

/* Example of MEMORY directive with overlay pages */ 

/**************************************************/ 

MEMORY 

{ 

PAGE 0: ROM : origin = Oh, length = lOOOh 

RAM : origin = lOOOOOh, length = OFOOOOOh 

OVR—MEM : origin = 1000h, length = lOOOh 

PAGE 1: OVR—MEM : origin = lOOOh, length = lOOOh 

PAGE 2: OVR—MEM : origin = lOOOh, length = lOOOh 


Figure 9-9. An Example of Overlay Pages 


This example defines three separate address spaces. PAGE 0 is the normal 
TMS34010 address space. It contains the memory ranges ROM and ram; sup¬ 
pose they represent all the memory in the normal address space. PAGE 0 also 
contains the first bank of overlay memory (ovr_mem). The other two address 
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spaces contain only the additional banks of overlay memory, both labeled 
ovr_mem. Note that all three ovr_mem ranges cover the same address range. 
This is possible because each range is on a different page, and therefore re¬ 
presents a different memory space. 



PAG El PAGE2 



Figure 9-10. Overlay Pages Defined by Figure 9-9 


9.8.2 Using Overlay Pages with the SECTIONS Directive 

The SECTIONS directive tells the linker which page an output section should 
be linked into. Each output section is assigned a page as well as an address. 
You can assign an output section to an overlay page by following the section 
specification with the PAGE option and a page number. Figure 9-11 shows 
the SECTIONS directive for Figure 9-9. 


SECTIONS 

{ 

. text 












{} 

> 

ROM 



/* 

Link 

. text 

in ROM on 

PAGE 0 

*/ 

. data 

{} 

> 

RAM 



/* 

Link 

. data 

in RAM on 

PAGE 0 

*/ 

.bss 

U 

> 

RAM 



/* 

Link 

.bss 

in RAM on PAGE 0 

*/ 

sectO 

{} 

> 

OVR—MEM 

PAGE 

0 

/* 

Link 

sectO 

into bank 

0 (PAGE 0) 

*/ 

sectl 

O 

> 

OVR-MEM 

PAGE 

1 

/* 

Link 

sectl 

into bank 

1 

*/ 

sect2 

} 

{} 

> 

OVR—MEM 

PAGE 

2 

/* 

Link 

sect2 

into bank 

2 

*/ 


Figure 9-11. SECTIONS Directive Definition for Figure 9-9 

If you don't specify a page number for an output section, the linker assumes 
PAGE 0 as the default. In this example, .text, .data, and .bss are all linked into 
the named memory areas on PAGE 0. (The PAGE 0 could be omitted from the 
sectO definition to achieve the same effect.) 

The PAGE specifications for sectO, sectl, and sect2 tell the linker to link 
these output sections into the corresponding overlay pages. As a result, they 
all are linked to address 1000h, but in different memory spaces. When the 
program is loaded, a loader can configure hardware in such a way that each 
of these sections is loaded into the appropriate bank of memory. 
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Within a page, you can bind output sections to addresses or memory areas in 
the usual way. In the preceding example, notice how sectl is bound to the 
memory range called OVR-MEM. This allows you to define the allocation of 
sections within a page, just as you can in a single memory space. For example: 

sectl 1200h: {} PAGE 1 

links sectl at address 1200h in page 1. If you do not specify any binding 
or named memory range for the section, the linker allocates the section wher¬ 
ever it can into the page (just as it does with a single memory space). For 
example, sect2 could also be specified as: 

sec2 : {} PAGE 2 

Since OVR-MEM is the only memory on PAGE 2, it is not necessary (but ac¬ 
ceptable) to specify > OVR—mem for the section. 

9.8.3 Syntax of Page Definitions 

As the preceding examples show, overlay pages are specified in the MEMORY 
directive by using the following syntax: 

MEMORY 

{ 

PAG E 0 : memory range 
memory range 


PAGE n : memory range 
memory range 

> 

Each page is introduced by the keyword PAGE and a page number, followed 
by a colon and a list of memory ranges that make up the page. Memory ranges 
are specified in the same manner as when no PAGE option is used. You can 
define up to 255 overlay pages. Since each page represents a completely in¬ 
dependent address space, memory ranges on different pages can have the 
same names. Configured memory on any page can overlap configured mem¬ 
ory on any other page. Within a single page, however, all memory ranges must 
have unique names and must not overlap . 

Any memory ranges listed outside the scope of a PAGE specification default 
to PAGE 0. Consider the following example: 


MEMORY 

{ 



ROM 

org = 

Oh 

len = 

lOOOh 


EPROM 

org = 

lOOOh 

len = 

lOOOh 


RAM 

org = 

2000h 

len = 

OEOOOh 

PAGE 1: 

XROM 

org = 

Oh 

len = 

lOOOh 

} 

XRAM 

org = 

2000h 

len = 

OEOOOh 

The memory 

ranges ROM, EPROM, and 

ram are all 

on PAGE 0 (since no page 

is specified). 

xrom and xram 

are on 

PAGE 1. 

Note that xrom on PAGE 1 


overlays ROM on PAGE 0 and xram on PAGE 1 overlays ram on PAGE 0. 

The link map listing is keyed by pages. This provides you with an easy method 
of verifying that you specified the memory model correctly. Also, the listing 
of output sections has a PAGE column that identifies the memory space into 
which each section will be loaded. 
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9.9 Default Allocation 

The MEMORY and SECTIONS directives provide flexible methods for build¬ 
ing, combining, and allocating sections. However, any memory locations or 
sections that you choose not to specify must still be handled by the linker. 
The linker uses default algorithms to build, combine, and allocate sections, 
within the specifications you supply. 

9.9.1 Allocation Algorithm 

If you do not use the SECTIONS directive, the linker uses the following SEC¬ 
TIONS definition: 

SECTIONS 

{ 


text 

ALIGN 

(16) : 

{ 

} 

data 

ALIGN 

(16) : 

{ 

} 

bss 

ALIGN 

(16) : 

{ 

} 

cinit 

ALIGN 

(16) : 

{ 

} /* For -c and -cr */ 


All .text input sections are concatenated to form a .text output section in the 
executable output file, all .data input sections are combined to form a .data 
output section, and all .bss sections are combined to form a .bss output sec¬ 
tion. Each output sections is aligned on a 16-bit (word) boundary and then 
allocated into configured memory. 

If you do not use the MEMORY directive, the linker assumes that the full 
32-bit address space is configured and available. Thus, under the default al¬ 
gorithm, the linker allocates output sections into memory beginning at lo¬ 
cation 0. 

If the input files contain named sections, the linker combines sections with the 
same names and allocates them following the .bss section. 

Note that if you use the SECTIONS directive, the linker performs no part of 
the default allocation. Allocation is performed according to the rules specified 
by the SECTIONS directive and the general algorithm described in Section 
9.9.2. 

9.9.2 General Rules for Output Sections 

An output section can be formed in one of two ways: 

Rule 1 : As the result of a SECTIONS directive definition. 

Rule 2: By combining input sections with the same names into output 

sections that are not defined in a SECTIONS directive. 

If an output section is formed as a result of a SECTIONS directive (rule 1), its 
specification in the directive completely determines its contents. (Section 9.7, 
page 9-16, tells you how to specify the contents of output sections.) 
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An output section can also be formed when input sections are encountered 
that are not specified by any SECTIONS directive (rule 2). In this case, the 
linker combines all input sections with the same name into an output section 
with this name. For example, suppose the files fl.obj and f2.obj both 
contain named sections called Vectors and that the SECTIONS directive 
does not define an output section called Vectors. The linker will combine 
the two Vectors sections from the input files into a single output section 
named Vectors, allocate it into memory, and include it in the output file. 

After the linker determines the composition of all the output sections, it must 
allocate them into configured memory. The MEMORY directive specifies 
which portions of memory are configured; if there is no MEMORY directive, 
the linker uses the default configuration. 

The linker's allocation algorithm attempts to minimize memory fragmentation. 
This allows memory to be used more efficiently and increases the probability 
that your program will fit into memory. This is the algorithm: 

1) Output sections for which you have supplied a specific binding address 
are placed in memory at that address. 

2) Output sections that are included in a specific named memory range or 
that have memory attribute restrictions are allocated. Each output sec¬ 
tion is placed into the first available space within the named area, con¬ 
sidering alignment where necessary. 

3) Any remaining sections are allocated in the order in which they are de¬ 
fined. Sections not defined in a SECTIONS directive are allocated in the 
order in which the linker encountered them. Each output section is 
placed in to the first available memory space, considering alignment 
where necessary. 
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9.10 Special Section Types (DSECT, COPY, and NOLOAD) 

You can assign three special types to output sections: DSECT, COPY, and 
NOLOAD. These types affect the way that a program is treated when it is 
linked and loaded. You can assign a type to a section following the section 
definition with the type (enclosed in parentheses). For example, 

SECTIONS 

{ 

seel 200000h (DSECT) : {fl.obj} 

sec2 400000h (COPY) : {fl.obj} 

sec3 600000h (NOLOAD) : {fl.obj} 

} 

• The DSECT type creates a "dummy section" that has the following quali¬ 
ties: 

- It is not included in the output section memory allocation. It takes 
up no memory and is not included in the memory map listing. 

- It can overlay other output sections, other DSECTs, and unconfig¬ 
ured memory. 

- Global symbols defined in a dummy section are relocated normally. 
They appear in the output module's symbol table with the same 
value they would have if the DSECT had actually been loaded. 
These symbols can be referenced by other input sections. 

- Undefined external symbols found in a DSECT cause specified ar¬ 
chive libraries to be searched. 

- The section's contents, relocation information, and line number 
information are not placed in the output module. 

In the preceding example, none of the sections from fl.obj are allo¬ 
cated, but all the symbols are relocated as though the sections were 
linked at address 200000h. The other sections can refer to any of the 
global symbols in seel. 

• A COPY section is similar to a dummy section, but its contents and as¬ 
sociated information are written to the output module. The . cinit 
section that contains initialization tables for the C compiler has this at¬ 
tribute under the RAM model. 

• A NOLOAD section differs from a normal output section in one respect: 
the section's contents, relocation information, and line number informa¬ 
tion are not placed in the output module. The linker allocates space for 
it, it appears in the memory map listing, etc. 
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9.11 Assigning Symbols at Link Time 

Linker assignment statements allow you to define external (global) symbols 
and assign values to them at link time. You can use this feature to initialize a 
variable or pointer to an allocation-dependent value. 


9.11.1 Syntax of Assignment Statements 

The syntax of assignment statements in the linker is similar to that of assign¬ 
ment statements in the C language: 


symbol 

= 

symbol 

+ = 

symbol 

- = 

symbol 

* = 

symbol 

/ = 


expression ; 
expression ; 
expression ; 
expression ; 
expression ; 


Assigns the value of expression to symbol 
Adds the value of expression to symbol 
Subtracts the value of expression to symbol 
Multiplies symbol by expression 
Divides symbol by expression 


The symbol should be defined externally in your program. If it is not, the linker 
defines a new symbol and enters it into the symbol table. The expression must 
follow the rules defined in Section 9.11.3. Assignment statements must be 
terminated with a semicolon. 


The linker processes assignment statements after it allocates all the output 
sections. Thus, if an expression contains a symbol, the address used for that 
symbol reflects the symbol's address in the executable output file. 

For example, suppose a program reads data from one of two tables identified 
by two external symbols, Tablel and Table2. The program uses the symbol 
cur—tab as the address of the current table. cur_tab must point to either 
Tablel or Table2. You could accomplish this in the assembly code, but you 
would need to reassemble the program in order to change tables. Instead, you 
can use a linker assignment statement to assign cur_tab at link time: 

prog.obj /* Input file */ 

cur—tab = Tablel; /* Assign cur-tab to one of the tables */ 


9.11.2 Assigning the SPC to a Symbol 

A special symbol, denoted by a dot (.), represents the current value of the SPC 
during allocation. The linker's "." symbol is analogous to the assembler's $ 
symbol. The "." symbol can only be used in assignment statements within a 
SECTIONS directive, because is only meaningful during allocation and 
SECTIONS controls the allocation process. 

For example, suppose a program needs to know the address of the beginning 
of the .data section. You can create an external undefined variable Dstart in 
the program by using the .global directive. Then, assign the value of to 

Dstart: 

SECTIONS 

{ 

.text: {} 

.data: { Dstart = .; } 

.bss : {} 

} 
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This defines the symbol Dstart to be the ultimate linked address of the .data 
section. (Dstart is assigned before .data is allocated.) The linker will relo¬ 
cate all references to Dstart. 

A special type of assignment assigns a value to the symbol. This adjusts 
the location counter within an output section and creates a hole between two 
input sections. Any value assigned to to create a hole is assumed to be 
relative to the beginning of the section and not the address actually repres¬ 
ented by Assignments to and holes are described in Section 9.12 
(page 9-32). 

9.11.3 Assignment Expressions 

These rules apply to linker expressions: 

• Expressions can contain global symbols, constants, and the C language 
operators listed in Table 9-2. 

• All numbers are treated as long (32-bit) integers. 

• Constants are identified in the same manner as they are by the assembler. 
That is, numbers are recognized as decimal unless they have a suffix (H 
or h for hexadecimal and Q or q for octal). C language prefixes are also 
recognized (0 for octal and Ox for hex). No binary constants are al¬ 
lowed. 

• Symbols within an expression have only the value of the symbol's ad¬ 
dress. No type checking is performed. 

• Linker expressions can be absolute or relocatable. If an expression 
contains any relocatable symbols (and zero or more constants or abso¬ 
lute symbols), it is relocatable. Otherwise, the expression is absolute. 
If a symbol is assigned the value of a relocatable expression, the symbol 
is relocatable; if assigned the value of an absolute expression, the symbol 
is absolute. 

The linker supports the C language operators listed in Table 9-2 in order of 
precedence. Operators in the same group have the same precedence. 

Besides the operators listed in Table 9-2, the linker also has an align operator 
that allows a symbol to be aligned on an /7-bit boundary within an output 
section (n is a power of 2). For example, the expression: 

. = align(16); 

aligns the SPC within the current section on the next 16-bit boundary. Since 
the align operator is a function of the current SPC, it can only be used in the 
same context as - that is, within a SECTIONS directive. 
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Table 9-2. Operators in Assignment Expressions 


Group 1 (Highest Precedence) 

Group 6 


Logical Not 

Bitwise Not 

Negative 

& 

Bitwise AND 

Group 2 

Group 7 

* 

/ 

% 

Multiplication 

Division 

Mod 

■ 

Bitwise OR 

Group 3 

Group 8 

+ 

Addition 

Minus 

&& 

Logical AND 

Group 4 

Group 9 

>> 

<< 

Arithmetic right shift 
Arithmetic left shift 

n 

Logical OR 

Group 5 

Group 10 (Lowest Precedence) 

! = 

> 

< 

< = 

> = 

Equal to 

Not equal to 

Greater than 

Less than 

Less than or equal to 

Greater than or equal to 

+ = 

* = 

/ = 

Assignment 

A+ = B -»> A=A+B 

A- = B A=A-B 

A* = B -> A=A* B 

A/ = B -> A=A/B 


9.11.4 Symbols Defined by the Linker 

The linker automatically defines several symbols that a program can use at run 
time to determine where a section is linked. These symbols are external, so 
they appear in the link map. They can be accessed in any assembly language 
module if they are declared with a .global directive. 

Values are assigned to these symbols as follows: 

.text is assigned the first address of the .text output section. 

(It marks the beginning of executable code.) 

etext is assigned the first address following the .text output section. 

(It marks the end of executable code.) 

.data is assigned the first address of the .data output section. 

(It marks the beginning of initialized data tables.) 

edata is assigned the first address following the .data output section. 

(It marks the end of initialized data tables.) 

.bss is assigned the first address of the .bss output section. 

(It marks the beginning of uninitialized data.) 

end is assigned the first address following the .bss output section. 

(It marks the end of uninitialized data.) 

emit is assigned the first address of the .cinit section (when -c or -cr is 
used). 
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9.12 Creating and Filling Holes 

The linker provides you with the ability to create areas within output sections 
that have nothing linked into them. These areas are called holes. In special 
cases, uninitialized sections can also be treated as holes. This section de¬ 
scribes how the linker handles such holes and how you can fill holes (and 
uninitialized sections) with a value. 

9.12.1 Initialized and Uninitialized Sections 

There are two rules to remember about the contents of an output section. An 
output section contains: 

Rule 1 : Raw data for the entire section or 

Rule 2: No raw data. 

A section that has raw data is referred to as initialized. This means that the 
object file contains the actual memory image contents of the section. When 
the section is loaded, this image is loaded into memory at the section's speci¬ 
fied starting address. The .text and .data sections always contain raw data if 
anything was assembled into them. Named sections defined with the .sect 
assembler directive also contain raw data. 

By default, the .bss section and named sections created with the .usect direc¬ 
tive contain no raw data; such sections are uninitialized. They occupy space 
in the memory map, but have no actual contents. Uninitialized sections typi¬ 
cally reserve space in RAM for variables. In the object file, an uninitialized 
section has a normal section header and may have symbols defined in it. 
However, no memory image is stored in the section. 

9.12.2 Creating Holes 

You can create a hole in an initialized output section. A hole is created when 
you force the linker to leave extra space between input sections within an 
output section. When such a hole is created, the tinker must follow rule 1 and 
supply raw data for the hole. 

Holes can only be created within output sections. There can also be space 
between output sections, but such spaces are not holes. There is no way to 
fill or initialize the space between output sections. 

To create a hole in an output section, you must use a special type of linker 
assignment statement within an output section definition. The assignment 
statement modifies the SPC (denoted by ".") by either adding to it, assigning 
a greater value to it, or aligning it on an address boundary. The operators, 
expressions, and syntax of assignment statements are described in Section 
9.11 (page 9-29). 
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The following example shows how assignment statements create holes in 
output sections: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

. += 100h; /* Create a hole with size lOOh */ 

file2.obj(.text) 

. = align(16); /* Create a hole to align the SPC */ 
file3.obj 

} 

} 

The output section outsect is built as follows: 

• The .text section from filel.obj is linked in. 

• The linker creates a 256-bit hole. 

• The .text section from file2.obj is linked in after the hole. 

• The linker creates another hole that aligns the SPC on a 16-bit boundary. 

• Finally, the .text section from file3.obj is included. 

All values assigned to the symbol within a section refer to the relative ad¬ 
dress within the section. The linker handles assignments to the symbol as 
if the section started at address 0 (even if you have specified a binding ad¬ 
dress). Consider the statement . = align(16) in the preceding example. 
This statement effectively aligns f ile3 . ob j .text to start on a 16-bit boundary 
within outsect. If outsect is ultimately allocated to start on an address that 
is not aligned, then f ile3 .text will not be aligned either. 

Expressions that decrement are illegal. For example, it is invalid to use the 
-= operator in an assignment to The most common operators used in as¬ 
signments to are + = and align. 

If an output section contains all input sections of a certain type (such as .text), 
you can use the following statements to create a hole at the beginning or end 
of the output section: 

.text: { . += 100h; } /* Hole at the beginning */ 

.data: { *(.data) 

. += lOOh; } /* Hole at the end */ 

Another way to create a hole in an output section is to combine an uninitial¬ 
ized section with initialized sections to form a single output section. In this 
case , the linker treats the uninitialized section as a hole and supplies data for 
it. An example of creating a hole in this way is: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

filel.obj(.bss) /* This becomes a hole */ 

} 

Since the .text section has raw data, outsect must also contain raw data (rule 
1). Therefore, the uninitialized .bss section becomes a hole. 
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Note that uninitialized sections only become holes when they are combined 
with initialized sections. If several uninitialized sections are linked together, 
the resulting output section is also uninitialized. 


9.12.3 Filling Holes 

Whenever there is a hole in an initialized output section, the linker must supply 
raw data to fill it. The linker fills holes with a 4-byte fill value that is replicated 
through memory until it fills the hole. The linker determines the fill value as 
follows: 


1) If the hole is formed by combining an uninitialized section with an ini¬ 
tialized section, you can specify a fill value for the uninitialized section. 
Follow the section name with an = symbol and a 4-byte constant: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

file2.obj(.bss) = OFFh /* Fill this hole */ 

3 /* 

with OOOOOOFFh */ 

} 


2 ) 


3) 


You can also specify a fill value for all the holes in an output section by 
supplying the fill value after the section definition: 


SECTIONS 

{ 

outsect: 

{ 

. +=* lOh; 
filel.obj(.text) 
filel.obj(.bss) 

} = OFFOOh 

} 


/* Create a hole */ 

/* Create another hole */ 
/* Fill both holes */ 
/* with OFFOOh */ 


If you do not specify an initialization for a hole, the linker fills the hole 
with the value specified with -f. For example, suppose the command file 
link. cmd contains the following SECTIONS directive: 


SECTIONS 

{ 

.text: { .= 100; } /* Create a 100-bit hole */ 

} 


Now invoke the linker with the -f option: 
gsplnk -f OFFFFFFFFh link.cmd 
This fills the hole with OFFFFFFFFh. 


4) If you do not invoke the linker with -f, the linker fills holes with Os. 

Whenever a hole is created and filled in an initialized output section, the hole 
is identified in the link map along with the value the linker uses to fill it. 
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9.12.4 Explicit Initialization of Uninitialized Sections 

An uninitialized section only becomes a hole when it is combined with an in¬ 
itialized section. When uninitialized sections are combined with each other, 
the resulting output section remains uninitialized and has no raw data in the 
output file. 

However, you can force the linker to initialize an uninitialized section by sup¬ 
plying an explicit fill value for it in the SECTIONS directive. This causes the 
entire section to have raw data (the fill value). For example, 

SECTIONS 

{ 

.bss: {} = 11223344h /* Fills .bss with 11223344h */ 

} 


Note: 

Since filling a section (even with Os) causes raw data to be generated for 
the entire section in the output file, your output file will be very large if 
you specify fill values for large uninitialized sections or holes. 
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9.13 Partial Linking 

An output file that has been linked can be linked again with additional mod¬ 
ules. This is known as partial linking or incremental linking. Partial linking 
allows you to partition large applications, link each part separately, and then 
link all the parts together to create the final executable program. 

Follow these guidelines for producing a file that you will relink: 

• Intermediate files must have relocation information. Use the -r option 
when you link the file the first time. 

• Intermediate files must have symbolic information. By default, the linker 
retains symbolic information in its output. Do not use the -s option if 
you plan to relink a file, because -s strips symbolic information from the 
output module. 

• Intermediate link steps should only be concerned with the formation of 
output sections, and not with allocation. All allocation, binding, and 
MEMORY directives should be performed in the final link step. 

The following example shows how you can use partial linking: 

• Step 1: Link the file filel.com; use the -r option to retain relocation infor¬ 
mation inthe output file tempoutl.out 

gsplnk -r -o tempoutl filel.com 
f ilel. com contains: 

SECTIONS 

{ 

ssl: { 

f1.obj 
f2.obj 


fn.obj 

} 


• Step 2: Link the file file2.com; use the -r option to retain relocation infor¬ 
mation inthe output file tempout2.out 

gsplnk -r -o tempout2 file2.com 

f ile2 . com contains: 

SECTIONS 

c 

SS2 : { 

gl.obj 
g2.obj 


gn.obj 

} 

• Step 3: Link tempoutl. out and tempout2 . out: 

gsplnk -m final.map -o final.out tempoutl.out tempout2.out 
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9.14 Linking C Code 

The TMS34010 C compiler produces assembly language source code that can 
be assembled and linked. For example, a C program consisting of modules 
progl, prog2, etc., can be linked to produce an executable file prog.out 
by invoking the linker with the following command: 

gsplnk -c -o prog.out progl.obj prog2.obj rts.lib [flib.lib] 

The -c option tells the linker to use special conventions that are defined by the 
C environment. The archive libraries rts.lib and flib.lib contain C run¬ 
time support functions. 

9.14.1 Runtime Initialization 

All C programs must be linked with an object module called boot . obj . When 
a program begins running, it executes boot.obj first. boot.obj contains 
code and data for initializing the runtime environment; the module performs the 
following tasks: 

• It sets up the system stack. 

• It processes the runtime initialization table and autoinitializes global 
variables (in the ROM model). 

• It disables interrupts and calls —main. 

The runtime support object library, rts . lib, contains boot . obj . You can: 

• Use the archiver to extract boot.obj from the library and then link the 
module in directly, or 

• Include rts.lib as an input file (the linker automatically extracts 
boot. obj when you use the -c or -cr option.) 

9.14.2 Object Libraries and Runtime Support 

The TMS34010 C Compiler Reference Guide describes additional runtime 
support functions that are included in rts.lib. If your program uses any of 
these functions, you must link rts. lib with your object files. 

If you are using floating point arithmetic, you must include the TMS34010 
floating-point library in your link. This library, called flib.lib, contains 
functions that a compiled program can call to perform floating-point oper¬ 
ations. If you do not use floating-point, you do not have to include this li¬ 
brary. 

You can also create your own object libraries and link them. The linker in¬ 
cludes and links only those library members that resolve undefined references. 

9.14.3 Autoinitialization (ROM and RAM Models) 

The C compiler produces tables of data for autoinitializing global variables. 
These tables are contained in a named section called .cinit. The initialization 
tables can be used in either of two ways. 


9-37 






Linker Description - Linking C Code 


• ROM Model (-c linker option) 

Variables are initialized at run time. The .cinit section is loaded into 
memory along with all the other sections. The linker defines a special 
symbol called cinit that points to the beginning of the tables in mem¬ 
ory. When the program begins running, the C boot routine copies data 
from the tables into the specified variables in .bss. This allows initial¬ 
ization data to be stored in ROM and then copied to RAM each time the 
program is started. 

Figure 9-12 illustrates the ROM autoinitialization model. 

Memory 


Initialization 

T ahioc 

(possibly ROM) 


.bss 


Figure 9-12. ROM Model of Autoinitialization 


• RAM Model (-cr linker option) 

Variables are initialized at load time. This enhances performance by re¬ 
ducing boot time and saving memory that would be used by the initial¬ 
ization tables. (Note that you must use a smart loader to take advantage 
of the RAM model of autoinitialization.) 

When you use -cr, the linker marks the .cinit section with a special at¬ 
tribute. This attribute tells the linker not to load the .cinit section into 
memory. The linker also sets the symbol cinit to -1; this tells the C 
boot routine that the initialization tables are not present in memory. 
Thus, no runtime initialization is performed at boot time. 

When the program is loaded, the loader must be able to: 

Detect the presence of the .cinit section in the object file. 

- Detect the presence of the attribute (STYP—COPY) that tells it not 
to copy the .cinit section. 

- Understand the format of the initialization tables (this is described 
in the TMS34010 C Compiler Reference Guide). 

The loader then uses the initialization tables directly from the object file 
to initialize variables in .bss. 

Figure 9-13 illustrates the RAM autoinitialization model. 




Object File 
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Linker Description - Linking C Code 


Object File Memory 



Figure 9-13. RAM Model of Autoinitialization 


9.14.4 The -c and -cr Linker Options 

The following list outlines what happens when you invoke the linker with the 

-c or -cr option. 

• The symbol -c-intOO is defined as the program entry point. 
_c_intOO is the start of the C boot routine in boot.obj; referencing 
_c_intOO ensures that boot.obj is automatically linked in from the 
runtime support library rts. lib. 

• The .cinit output section is padded with a termination record (two bytes 
filled with Os) so that the boot routine (ROM model) or loader (RAM 
model) knows when to stop reading the initialization tables. 

• In the ROM model (-c option), the linker defines the symbol cinit as 
the starting address of the .cinit section. The C boot routine uses this 
symbol as the starting point for autoinitialization. 

• In the RAM model (-cr): 

The linker sets the symbol cinit to -1. This indicates that the 
initialization tables are not in memory, so no initialization is per¬ 
formed at run time. 

- The STYP—COPY flag (01 Oh) is set in the .cinit section header. 
STYP—COPY is the special attribute that tells the loader to perform 
autoinitialization directly and not to load the .cinit section into 
memory. The linker does not allocate space in memory for .cinit. 
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9.15 Linker Example 

This example links three object files named demo.obj, fft.obj, and ta¬ 
bles, obj and creates a program called demo.out. The symbol setup is the 
program entry point. 

Assume that target memory has the following configuration: 


Address Range: 
00000 to 1 FFFF 
20000 to 2FFFF 
30000 to 3FFFF 
40000 to FFFFFFFF 


Memory Contents: 

Video RAM 
General-purpose RAM 
No physical memory 
ROM 


The output sections are constructed from the following input sections: 


• The .text output section contains executable code. It is constructed from 
the .text sections of input files demo.obj and labels.obj, and must 
be allocated into ROM. 

• The .data output section contains initialization data. It is constructed 
from the .data sections of input files tables.obj and labels.obj, and 
must also be allocated into ROM. In addition, the application requires 
that the .data sections from the two files be separated by 128 bits, all of 
which are set to 1. 

• An output section named screen is constructed from the .bss section 
of demo.obj. This section defines the screen memory; it must be linked 
into video RAM and initialized with the value 8Fh. 

• The .bss output section contains the .bss section from input file la¬ 
bels, obj. This section defines global and static data; it must be linked 
into general-purpose RAM, and does not need to be initialized. 

• An output section named int_vecs is constructed from the int_vecs 
section of tables.obj. This section contains interrupt vectors; it must 
be allocated in ROM at address OFFFFFFEOh. 

Figure 9-14 illustrates the linker command file for this example; Figure 9-15 

illustrates the map file. 
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^z**********************************************************************/ 
/**** Specify Linker Options ****/ 


-e SETUP 
-o demo.out 
-m demo.map 


/* Define the entry point 
/* Name the output file 

/* Create a load map 


/**** Specify the Input Files ****/ 

demo.obj 
tables.obj 
labels.obj 

/**********************************************************************/ 
/**** Specify the Memory Configuration ****/ 

/**********************************************************************/ 


MEMORY 

{ 

VIDEO: 

RAM: 

ROM (R) 

} 

SECTIONS 

{ 


origin = Oh, length = 20000h 

origin = 20000h, length = lOOOOh 

origin = 40000h, length = FFFCOOOOh 


/* Read only */ 


.text: {} >ROM 

.data: 

{ 

tables.obj(.data) 

. += 128; 
labels.obj(.data) 

} = OFFFFFFFFh >ROM 

screen: 

{ 

demo.obj(.bss) 

} = 8F8F8F8Fh >VIDEO 

.bss: {} >RAM 

int_vecs OFFFFFFEOh: { } 


/* Link all .text sections into ROM */ 
/* Link the .data sections */ 

/* Create a 128-bit hole */ 
/* Fill the hole */ 
/* Create a new section for screen mem */ 


/* Link all remaining .bss sections */ 

/* Link and bind interrupt vectors */ 


} 

/**********************************************************************/ 
/**** End of Command File ****/ 


Figure 9-14. Linker Command File, demo.cmd 


Invoke the linker with the following command: 

gsplnk demo.cmd 

This creates the map file shown in Figure 9-15 and an output file called 
demo. out that can be run on the TMS34010. 
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***************************************************************** 

1 GSP COFF 

Linker, Version 

1.04,85.319 



***************************************************************** 

OUTPUT FILE NAME: <demo.out> 



ENTRY POINT SYMBOL: "SETUP” address 

: 00040000 


MEMORY CONFIGURATION 





name origin 

length attributes | 


VIDEO 00000000 000020000 RWIX 


RAM 00020000 000010000 RWIX 


ROM 00040000 

DFFFC0000 R 


SECTION ALLOCATION MAP 




output 



attributes/ 


section 

origin 

length 

input sections 


screen 

00000000 

00002000 




00000000 

00002000 

demo.obj (.bss) [fill = 8f8f8f8f] 

.bss 

00020000 

000000200 

UNINITIALIZED 



00020000 

000000200 

labels.obj (.bss) 


. text 

00040000 

000007110 




000400000 

000007110 

demo.obj (.text) 


. data 

00047110 

00000b600 




00047110 

000003190 

tables.obj (.data) 



0004a2a0 

000000080 

--HOLE-- [fill = ffffffff] 


0004a320 

000003190 

labels.obj (.data) 



0004a4b0 

000003190 

demo.obj (.data) 


int—vec 

ffffffeO 

000000020 




ffffffeO 

000000020 tables.obj (int- 

vecs) 

GLOBAL SYMBOLS 




address 

name 


address 

name 

00040000 

SETUP 


00000000 

extvar 

0004006e 

cont 


00020200 

end 

00052710 

edata 


00040000 

SETUP 

00020200 

end 


0004000a 

start 

00047110 

etext 


0004006e 

cont 

00000000 

extvar 


00040104 

sub 

0004d4b0 

list 


00047110 

etext 

0004d4ce 

main 


0004d4b0 

list 

0004d4ba 

plasm 


0004d4ba 

plasm 

0004d4c4 

p2asm 


0004d4c4 

p2asm 

0004000a 

start 


0004d4ce 

main 

00040104 

sub 


00052710 

edata 

[12 symbols] 





Figure 9-15. Output Map File, demo.map 


9-42 














Section 10 


Object Format Converter Description 


Most EPROM programmers do not accept COFF object files as input. The 
object format converter converts a COFF object file into one of three object 
formats that most EPROM programmers accept as input: 

• Tektronix hex object format: This format supports 32-bit addresses. 

• Intel hex object format: This format supports 16-bit addresses. 

• Tl-tagged object format: This format supports 16-bit addresses. 


Note: 

If your code uses addresses that are significant to more than 16 bits, use 
the Tektronix format. 


The object format converter accepts one COFF object file as input. If you are 
converting to Tl-tagged object format, the utility produces one output file. If 
you are converting to Tektronix or Intel object format, the utility produces two 
output files: one output file contains the high (most significant) bytes, and the 
other file contains the low (least significant) bytes. 

This section contains the following topics: 


Section Page 

10.1 Object Format Converter Development Flow .10-2 

10.2 Invoking the Object Format Converter .10-3 

10.3 Object Format Converter Examples ...10-4 
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Object Format Converter Description - Development Flow 


10.1 Object Format Converter Development Flow 

Figure 10-1 illustrates the object format converter's role in the assembly lan¬ 
guage development process. 



Figure 10-1. Object Format Converter Development Flow 
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Object Format Converter Description - Invocation 


10.2 Invoking the Object Format Converter 

To invoke the object format converter, enter: 

gsprom [-option] [COFF input file [output filej [output fHe 2 ]]] 

gsprom is the command that invokes the object format converter; all param¬ 
eters are optional. The options can be entered anywhere on the line, but the 
order of filenames is significant. The filenames (if used) are interpreted as: 

1) The input filename, 

2) The output filename (for Tl-tagged format) or the high-byte output 
filename (for Tektronix or Intel format), and 

3) The low-byte output file (for Tektronix or Intel format). (If you specify 
Tl-tagged format and name a third file, the utility ignores the third file¬ 
name.) 

• There are three options: 

-i specifies Intel hex object format for the output. 

-t specifies Tl-tagged object format for the output. 

-x specifies Tektronix hex object format for the output. 

If you don't specify an option, the object format converter produces 
Tektronix hex format output files. 

• If you do not specify an input filename, the object format converter 
prompts for it. If you specify a filename without an extension, the utility 
assumes that the filename has a default extension of .obj. 

• If you do not specify a second filename, the object format converter uses 
the input filename with an extension of: 

- .tag (for Tl-tagged format) or 

- .hi (for Tektronix or Intel format). 

• If you do not specify a filename for the low-byte output file but do spe¬ 
cify a name for the high-byte output file, the object format converter 
uses the high-byte file name with an extension of Jo. If you do not 
specify a filename for the low-byte file or the high-byte file, the object 
format converter uses the input filename with an extension of Jo. 

When the utility finishes converting the input file, it prints the message 

Translation complete. 
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10.3 Object Format Converter Examples 

Here are some examples of using the object format converter. 

• Example 1: 

You can invoke the object format converter with no options and no fi¬ 
lenames: 

gsprom 

The utility will print the following banner and prompt: 

COFF Object Converter Version 5.01, 87.610 
(c) Copyright 1987, Texas Instruments Inc. 

Coff file [.obj]: 

If, for example, you respond to the prompt with a filename of fft, the 
object format converter uses the file fft. obj as an input file. The utility 
produces two output files named fft.hi and fft.lo in Tektronix hex 
format. (Tektronix format is the default when you don't specify a for¬ 
mat.) 

• Example 2: 

If you enter: 

gsprom -i in outl out2 

the utility uses in.obj as the input file. It creates two Intel hex format 
files named outl .hi and out2 . lo. 

• Example 3: 

If you enter: 

gsprom -x in.tmp out.x 

the object format converter uses in.tmp as the input file. It produces 
Tektronix hex format output; the high-byte file is named out. x, and the 
low-byte file is named out.lo. 

• Example 4: 

If you enter: 

gsprom -t test 

the object format converter uses test.obj as the input file. It produce 
an output file named test.tag in Tl-tagged format. 

There are two situations in which the object format converter aborts execution: 

1) If any of the specified files cannot be opened, the object format converter 
prints the message Input COFF file cannot be opened and aborts. 

2) If you supply the utility with the name of an invalid object file, the object 
format converter prints the message Corrupt input file and aborts. 
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Section 11 


Simulator Description 


The TMS34010 simulator is a debugging tool that provides software simu¬ 
lation of the TMS34010 hardware functions and of a configurable graphics 
environment. The simulator command set displays and maintains graphics and 
machine status information, and controls execution of the software system 
under development. 

The simulator can be used to design, implement, and evaluate both graphics 
and nongraphics software systems. The simulator: 

• Allows complete control over the simulation status 

• Recognizes the entire TMS34010 assembly language instruction set 

• Uses memory efficiently to simulate both TMS34010 program memory 
and screen memory 

• Simulates the host interface, memory controller, and cache operation 

• Supports breakpoints and traces on a variety of memory accesses 

• Displays the machine state in a screen-oriented format 

• Provides a versatile methods of command entry, with error reporting, file 
input, and multiple command buffers 

• Provides statistical information that allows you to evaluate program 
performance, including the cache hit/miss ratio 

The simulator's relative execution speed depends on the host system; MS- 
DOS and PC-DOS systems generally operate 20,000 times slower than the 
TMS34010. 

Topics in this section include: 


Section Page 

11.1 Invoking the Simulator .11-3 

11.2Simulator Development Flow . 11-2 

11.3 Hardware and System Requirements .11 -4 

11.4Screen Displays .11-5 

11.5 Entering Commands. 11-11 

11.6System Simulation .11-17 

11.7 Demonstration Program .11 -22 

11.8Simulator Commands .11 -24 
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Simulator Description - Development Flow 


11.1 Simulator Development Flow 

Figure 11-1 illustrates the simulator's role in the assembly language develop¬ 
ment flow. The simulator accepts linked COFF object files as input. 
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Figure 11-1. Simulator Development Flow 
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Simulator Description - Invocation 


11.2 Invoking the Simulator 

To invoke the simulator, enter one of these two commands: 
IBM-PC : gspsim [-options] [object file [offset] ] 
TI-PC : gspsimt [-options] [object file [offset] ] 


gspsim is the command that invokes the simulator on an IBM-PC. 

gspsimt is the command that invokes the simulator on a TI-PC. 

options are optional parameters. When used, options must be preceded 
by a hyphen; bad options are ignored. Valid options include: 

-f tells the simulator to expect input from the command input 
file gspinput. 000. 

-t disables the special trap functions that the simulator nor¬ 
mally associates with traps 27, 28, and 29. 

object file is an optional parameter. It specifies a COFF object module that 
the simulator loads and executes following invocation. 

offset is an optional parameter; you can use it when you specify a load 

file. The simulator relocates the object module by adding the 
offset to all the relocation entries in the module. 

The simulation session begins after you invoke the simulator; the simulator: 

1) Displays its banner, 

2) Turns on the graphics card, 

3) Loads the object module (if specified), 

4) Performs a reset, and 

5) Displays the initial screen shown in Figure 11 -2. 
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Figure 11-2. Initial Simulator Display 
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Simulator Description ~ Hardware and System Requirements 


11.3 Hardware and System Requirements 

The simulator runs on 8088, 8086, and compatible derivatives (using MS- 
DOS versions 2.11 and higher or PC-DOS versions 2.1 and higher). MS-DOS 
systems that are directly supported include: 

• The IBM-PC, PC/XT, PC/AT, and compatible machines with 512K bytes 
of memory and CGA emulation. 

• The TI-PC with 3-plane color graphics support and 512K bytes of me¬ 
mory. 

System requirements for operating the simulator include: 

• A host operating and display system as described above. 

• An editor for manipulating TMS34010 assembly language and source 
files. 

• The TMS34010 assembler and linker (and optionally the TMS34010 C 
compiler) for creating object files. 

In addition, you need a working knowledge of the TMS34010 instruction set. 
On an IBM-PC, you must have the following CONFIG.SYS file: 

BUFFERS = 20 
FILES = 20 

DEVICE = C:/MSDOS/ANSI.SYS 

A copy of this file is shipped with the simulator. Your system must be con¬ 
figured so that the CONFIG.SYS file can install the ansi.SYS device driver 
when the system is booted. 

We suggest that you create a directory called \gsptools to contain the sim¬ 
ulator and the simulator help files. Use the DOS SET command to equate the 
\gsptools pathname with the name gspdir; for example, 

IBM-PC: SET GSPDIR=C: \GSPTOOLS 

TI-PC: SET GSPDIR=E:\GSPTOOLS 

(Be sure to enter the command exactly as shown - with uppercase letters and 
without blanks except as shown.) This allows the simulator to access the help 
files from other directories. 
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Simulator Description - Screen Displays 


11.4 Screen Displays 

The TMS3401 0 simulator displays two separate sets of information: 

• The machine-state display, which provides a complete set of status 
and statistical information. 

• The simulated graphics display (also called the graphics environ¬ 
ment). 

11.4.1 Machine-State Display 

The simulator updates the machine-state display when it executes commands. 
Figure 11-3 shows the initial machine-state display. Each field in this illus¬ 
tration is numbered; the numbers are keyed to the list that follows the illus¬ 
tration. 
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Figure 11-3. Simulator Display Format 


1) Register Display. This area displays the TMS34010 internal registers. You 
can display two sets of registers: 

• The general-purpose register files (A and B) and the stack pointer or 

• I/O registers. 

The general-purpose registers are the default display. During graphics oper¬ 
ations, the B-file registers have special functions; these functions are listed 
with the registers in the display. When the simulator lists the I/O registers, it 
displays their functions and their addresses. 
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The DR command toggles the display between the general-purpose registers 
and the I/O registers. For an example of the I/O register display, see the DR 
command. 

2) Field Information: This area of the screen (FS and FE) displays the sizes 
of fields 0 and 1, respectively, followed by their respective field extension bits 
(FEO and FE1). The first values for FS and FE apply to field 0; the second 
values apply to field 1. All four of these values are extracted from the status 
register; they are displayed as decimal numbers. 

FSO is selected independently of FS1. Status bits 0-4 select field size 0, bits 
6-10 select field size 1. Valid field sizes range from 0 to 32 bits. 

FEO is selected independently of FE1. Status bit 5 selects the field extension 
type of field 0, bit 11 selects the field extension type of field 1. A value of 0 
indicates zero extension, 1 indicates sign extension. 

The field size and field extension used by the current instruction are high¬ 
lighted in green. If the current instruction does not use a field size or exten¬ 
sion, then both sets of values are displayed in yellow. 

3) Pixel Size: This area of the screen (PS) displays the current pixel size (this 
is the value in the PSIZE register). Valid pixel sizes include 1, 2, 4, 8, and 16 
bits per pixel. 

4) Plane Mask: This area (PM) displays the value of the plane mask (this is the 
current value of the PMASK register). 

5) Windowing Option: This area (W) displays the current windowing option, 
which is selected by setting bits 6 and 7 of the CONTROL register. Valid 
windowing options include: 

W = off windowing is not enabled. 

W = int any attempt to write inside the window generates an interrupt, 
and no pixels are drawn. 

W = on if the object lies entirely within the window, it's drawn, otherwise 
no pixels are drawn. 

W = pick (also called window dip.) The portion of the object that lies in¬ 
side the window is drawn. 

If a window option other than off is selected, it is highlighted in cyan. 

6) Pixel Processing Option: This area of the screen (pp) lists the currently 
selected pixel processing option, which is selected by bits 10-14 of the 
CONTROL register. The S-+D pixel processing option is the default; any other 
option that is selected is highlighted in cyan. For a list of valid pixel process¬ 
ing options, see the PP simulator command. 

7) Monitor Status Messages: This area displays the current status of the 
TMS34010 simulator; the messages are self explanatory. 
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8) Cache Status: This area of the screen indicates whether the last instruction 
executed was in cache. Messages that may be displayed include: 

Cache off the cache is not enabled. 

Cache miss the cache is enabled but does not contain the currently exe¬ 
cuting instruction. 

Cache hit the cache is enabled and contains the currently executing in¬ 
struction. 

Cache operation is simulated during execution and reverse-assembly. If, when 
cache is enabled, you display a memory location to which the PC is pointing, 
you may not see a change in the machine-state display and in the actual op¬ 
code that is executed. This is faithful to actual TMS34010 operation with the 
cache enabled. To avoid this situation, use the CF command to flush the 
cache or the CD command to toggle the CD bit in the CONTROL register. 

The simulator maintains a record of cache statistics when the cache is enabled. 
These statistics include: 

• A total count of cache accesses and 

• The ratio of hits to misses (listed as a percentage). 

Use the DC (display cache) command to display the cache status in the 
scratch area. The CLCS (clear cache statistics) command resets these statis¬ 
tics to 0. 

9) Clock Timing: This area (CLK) displays the number of clock cycles con¬ 
sumed thus far in the instruction simulation. The clock value is based on in¬ 
struction execution times and memory accesses. This clock value does not 
represent the amount of time consumed by the TMS34010 system for video 
timing, RAM refresh, or shift register access. The initial clock cycles value is 
4, for the 4 clock cycles consumed by fetching the PC from the trap 0 vector 
for reset. One clock cycle is 1 60 ns. 

10) Status Register: This area (ST) displays the status register contents. 

11) Status Elements: This area displays the current values of four status bits 
contained in the status register. These include: 

N sign bit 
C carry bit 
Z zero bit 
V overflow bit 

12) Control Elements: This area displays the current values of five bits con¬ 
tained in the status and CONTROL registers, including: 

I refers to the IE (interrupt enable) bit in the status register. Setting IE=0 
disables all maskable interrupts; setting IE = 1 enables all maskable inter¬ 
rupts. 

T refers to the transparency bit in the CONTROL register. Setting T=0 
disables transparency; setting T=1 enables transparency. 
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P refers to the PBX (PIXBLT executing) bit in the status register. The 
TMS34010 sets this bit when a PIXBLT or FILL instruction is interrupted. 
PBX=1 indicates that the interrupt occurred on an instruction boundary; 
PBX=1 indicates that the interrupt occurred during instruction execution. 

V refers to the PBV (PIXBLT vertical direction) bit in the CONTROL regis¬ 
ter. This bit determines the vertical direction for PIXBLT instructions that 
use XY addressing. Setting PBV^O increments the Y dimension (move 
from top to bottom); setting PBV=1 decrements the Y dimension (move 
from bottom to top). 

H refers to the PBH (PIXBLT horizontal direction) bit in the CONTROL re¬ 
gister. This bit determines the horizontal direction for PIXBLT in¬ 
structions that use XY addressing. Setting PBH=0 increments the X 
dimension (move from left to right); setting PBH = 1 decrements the X 
dimension (move from right to left). 

13) Stack Pointer: This area (SP) displays the contents of the stack pointer. 

14) Control Register: This area (CTL) displays the contents of the CONTROL 
register. 

15) Program Counter: This area (PC) displays the current contents of the 
program counter. 

16) Data at the Location Pointed to by the PC. The area following the PC 
displays the value of the word that the PC is pointing to and the word's re¬ 
verse-assembly. 

17) Last Instruction Executed. This area contains the reverse-assembly of the 
last instruction that was executed. If this instruction is the same as the current 
instruction, it is displayed in green; otherwise, it is displayed in cyan. Specific 
error messages and breakpoint halt conditions are also displayed in this area. 

18) Graphics and Scratch Display Area (10 lines). This is the scratch display 
area. Information is listed in the 10 blank lines between the reverse-assembly 
line and the command line. 

19) Command Prompt and Current Buffer. This line prompts for command 
entry and displays the current buffer. The simulator maintains ten command 
buffers (0-9) for storing commands before or after their execution. 

20) Command Entry Line. This is where you enter commands. Except for 
menu-driven commands, information is only entered from the command line 
in the space following the command prompt. Commands are displayed in 
uppercase; even if you enter them in lowercase, the simulator immediately 
translates them to uppercase. The simulator cursor is a shaded, blinking rec¬ 
tangle; in this document, it is represented by the character —. 

21) Last Command Entered. The simulator echoes the last command entered 
by displaying it beneath the command line. 
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11.4.2 Displaying Graphics and Status Information Simultaneously 

The graphics display and the machine-state display can be viewed separately 
or simultaneously on monitors with independent text and graphics displays 
(such as the TI-PC). In this situation, the machine-state and graphics displays 
can be independently toggled, producing four possible combinations of screen 
information: 

• Graphics display with machine-state display superimposed (default) 

• Machine-state display only 

• Graphics display only 

• Blank screen with command line 

On monitors with interdependent text and graphics, these two sets must be 
viewed alternately: 

• Machine-state display only (default) 

• Graphics display only 

You can use the TX and GR commands to swap display modes. 

11.4.3 Using the HELP Function 

You can type HELP or H at any time to display the help utility menu. The help 
utility contains a menu that lists classes of instructions. Invoking any of these 
calls up a file on the host that contains reference information about the com¬ 
mands. 


Note: 

The help files must be: 

1 ) In the current directory on the current disk or 

2) In the directory specified with GSPDIR (see Section 11.3 on page 
11-4). 


The help files contain an initial listing followed by a brief summary of each 
commands syntax and action. Figure 11-4 (page 11-10) illustrates the help 
menu. 
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Figure 11-4. Simulator Help Menu 
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11.5 Entering Commands 

The simulator supports a set of general commands as well as 
TMS34010-specific commands. 

Initially, all commands are entered on the command line, as shown in Figure 
11 -3 on page 11 -5. You can enter commands in uppercase or lowercase, or 
in any combination; the simulator converts them to uppercase before it inter¬ 
prets them. As you enter commands, the simulator places them in the cur¬ 
rently active command buffer to be executed. The command line is the line 
that contains the prompt; 

Command[0] 

In this example, the number 0 indicates that command buffer 0 is the active 
buffer. The prompt and cursor generally appear as: 

Command[1] — 

(— shows the cursor position.) The command line contains the most recent 
command entered into the command buffer. You can type over it or edit it to 
enter a new command. The line beneath the command line echoes the most 
recently stored command; you cannot edit this line, but the simulator updates 
it as commands are executed or stored. 

The simulator allows you to edit the command line with some simple editing 
keys: 


• Backup one character. Use one of the following: 

- key, 

- backspace key, 

- control-S keys, or 

- control-H keys. 

• Forward one character. Use one of the following: 

- -» key or 

- control-D keys. 

• Forward one word. Use one of the following: 

- tab key or 

- control-F keys. 

• Backward one word. Use one of the following: 

- shift-tab keys or 

- control-A keys. 

• Delete character. Use one of the following: 

- delete key or 

- control-G keys. 

• Insert characters. Use one of the following: 

- insert key or 
control-V keys. 
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After you type a command name (and edit it, if necessary), type either a line¬ 
feed, control-J, or CR. (carriage return) so that the simulator can process the 
command: 

• CR truncates the command, and executes the portion of the command 
to the left of the cursor. 

• linefeed and control-J execute the entire command line. 

You can re-execute a command by placing the cursor in the leftmost position 
and entering a carriage return. You can enter multiple commands on one line 
by separating them with semicolons. 


11.5.1 Command Parameters 


Some simulator commands have numeric parameters; you can use decimal or 
hexadecimal numbers. Numeric parameters default to the format that is most 
often used for a particular parameter. For example, addresses default to hex, 
register numbers default to decimal, and register contents default to hex. 

You can override default formats by using one of these characters: 

% (prefix) specifies decimal format. 

H (suffix) specifies hexadecimal format. 

You can also specify a negative number (whether or not you are overriding the 
default format) by prefixing it with a minus sign (-). 

Here are some examples of that use numeric parameters. These examples use 
the A command to modify or display the contents of an A-file register. The 
syntax for the A command is: 


A n register value 

(n is a register number in the range 0-14.) The default format for the value is 
hexadecimal. All of the following commands set the contents of register A12 
to OFFFFFFFFh. 


Command[1] 
Command[1] 
Command[1] 
Command[1] 
Command[1] 
Command[1] 


A12 FFFFFFFF 
A% 12 FFFFFFFF 
ACH FFFFFFFF 
A12 -1 
A12 -%1 
ACH -1H 


Note: 

All memory references are specified as bit addresses. Thus, the last ASCII 
character of all word-aligned addresses is 0. The last four bits of memory 
addresses that are specified on the command line are forced to 0, unless 
otherwise stated. 


You can also use a register as a numeric parameter to specify a 32-bit value. 
The format for this type of parameter is R n; n can be: 
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• A0-A14 (an A-file register) 

• B0-B14 an B-file register) 

• SP (the tack pointer), 

• PC (the program counter), or 

• ST (the status register). 

You can also use the X half (16 LSBs) or Y half (16 MSBs) of a register to 
specify a 16-bit numeric parameter. The formats for these types of parameters 
are RX/7 and HYn. 

For example, you can load register A1 2 with the the contents of the status 
register: 

Command[1] A12 RST 

You can load the stack pointer with the contents of the program counter: 

Command[1] SP RPC 

You can use the MM command to change the contents of a single word that 
the SP points to: 

Command[1] MM RSP OFFFFh 

You can also use the R prefix to access A- and B-file registers. The first ex¬ 
ample below negates the contents of register A14. The second example mo¬ 
difies the two words pointed to by the SP with the contents of register B2. 
The third example modifies the contents of a single word pointed to by register 
B8 with the Y half of register A1. 


Command[1] 

A14 

-RA14 

Command[1] 

MM 

RSP RB2 

Command[1] 

MM 

RB8 RYAl 


11.5.2 Command Buffers 

The simulator maintains 10 command buffers for storing commands before or 
after their execution. The active command buffer is indicated by the value in¬ 
side of the square brackets following the Command prompt. The initial default 
buffer is 0, indicated by: 

Command[0]. 

You can select a command buffer by entering one the following as the first 
character on the line: 

• A number (0-9) selects a specific buffer. 

• + or T advances to the next buffer. 

• - or i goes to the previous buffer. 

Changing to a new buffer does not change the contents of the current buffer. 

You can use multiple command buffers to store specific commands. This al¬ 
lows you to execute a chain of commands with fewer keystrokes. Command 
buffers can be chained together to provide lengthy command sequences. To 
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chain several buffers together, specify the next buffer to be executed as the last 
command on the command line: 

Command[0] SS; DM 0 200; 1 

This example single-steps, displays memory from address 0 to address 200, 
and then executes the contents of buffer 1. A buffer can even reference itself 
to provide a simple looping mechanism. 

Command[0] A 13 340990BC 
A 13 340990BC 

Command [ 0 ] 5 C/?13 340990BC 

A 13 340990BC 

Command!5] HELP 
HELP 


In this case, buffer 0 still contains the command A 13 340990BC which can 
be re-executed by returning to buffer 0. 

You can use the + , -, t, and i keys to move through the buffers: 


Command[0] A 13 340990BC 
A 13 340990BC 

Command [ 0 ] + CA?13 340990BC 

A 13 340990BC 

Command[1] HELP 
HELP 


Command[1] - CR ELP 

HELP 


Command[0] A 13 340990BC 
A 13 340990BC 


Buffer 0 still contains the command A 13 340990BC, which can be re- 

executed by returning to buffer 0. 

You can store a string of commands in a buffer without executing them by 
preceding the string with an ! character: 

Command[l] !A 13 45; A14 6000; ru n CR 
A9 801AC 

Command[1] A 13 45; A14 6000; run 

A 13 45; A14 6000; run 
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11.5.3 Loading and Running Code 

Use the L command to load object code into the simulator. The syntax is: 

L filename [offset] 

This command provides the object file name and an optional signed program 
memory offset. 

The following example loads file coda.out. 

Command[1] L CODA.OUT 10200 

The simulator will open coda.out, read its contents, interpret it, and load it 
into the simulated memory using the offset 00010200h. Note that this value 
offsets any addresses given in the object module. 

You can offset any object code file by specifying the offset value as a param¬ 
eter of the L command. Figure 11 -5 describes protected (allocated) areas of 
memory. Beware of offsetting nonrelocatable files. 


Memory Space Contents 


OFFFFFFFOh 

thru 

OFFFFFCOOh 


0C00001FOh 
thru 

OCOOOOOOOh 


End of Available 
Memory 
thru 

OOOOOOOOh 


Traps 


I/O Registers 


Screens 

and 

Program 


Figure 11-5. Dedicated and Available TMS34010 Memory Spaces 


Note that the simulator cannot check to see if screen or program boundaries 
are violated. Screen and program spaces are distinguished only by how you 
treat them; therefore, any area of available memory can be used for either 
purpose. If you attempt to write to a memory location outside of the defined 
memory range, the simulator issues an error message and halts. 
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11.5.4 Line Assembler 

The simulator can assemble single lines of TMS34010 assembly language 
code. It places the resulting opcodes and operands into memory via the MM 
command. The line assembler accepts only absolute numeric values. 

11.5.5 Error Reporting 

Errors are reported in several ways: 

• If you enter a command or parameter incorrectly, the simulator displays 
an error message on the line beneath the command line. These error 
messages are usually diagnostic (for example, they can show you why 
an entry was incorrect). For example, 

Command[1] && 4@ CR 

A 9 34010 

Command[1] &Et 4@ 

Command not recognized; re-enter 

Command[1] && 4@ 

&& 4@ 

Command error messages of this sort are queued (stored up), and re¬ 
main available for viewing until the list is exhausted. You can clear a 
message by typing ESC ; each message requires a separate ESC before 
control returns to the command line. The simulator does not remove the 
incorrect command from the buffer; this allows you to edit and re-enter 
it. 

• Instruction execution errors are displayed in red in the scratch display, 
and remain displayed until you clear them (use CLS) or until other in¬ 
formation is displayed. 
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11.6 System Simulation 

The simulator's chief purpose is to accurately simulate the TMS34010 in¬ 
struction set. Where there are deviations, they have been made in the interest 
of providing a more useful simulation tool (for example, traps 29-27 have re¬ 
served functions). The simulator does not simulate the video timing, RAM 
refresh, and shift register operations implied by I/O registers. 

11.6.1 Local Memory Simulation 

The memory that is available for simulated local memory is determined by the 
memory available on the host. The definition (beginning and ending ad¬ 
dresses, on-screen and off-screen memory) can be specified with the M 
command. Memory is accessed by the program counter, the host interface, 
and the TMS34010 instruction set via the cache and memory controller sim¬ 
ulation. These accesses to memory can be monitored via the trace (TR) and 
breakpointing (BP) features of the simulator. Up to 20 trace and/or break¬ 
point definitions are allowed at any one time. You can also access memory 
directly via simulator commands (F - fill memory, MM - memory modify, DM 
- display memory, and 10 - display/modify I/O registers, etc.) in which case 
trace and breakpointing are inhibited. 

The graphics display (when enabled) reflects changes that affect on-screen 
memory, except when a program is downloaded. 

11.6.2 Interrupts Simulation 

The simulator simulates the TMS34010 interrupt structure through a a timing 
schedule. Use the I command to define this schedule; you can supply a count 
and a frequency of occurrence selection for each interrupt (including RESET, 
INTI, INT2, INT3, NMI, HOST, DISP, and WV). 

Interrupts are handled when they occur in a priority fashion and index into the 
trap and interrupt vector table for the beginning of the interrupt handling 
routine. The INTPEND and INTENB registers and their effect on the handling 
of interrupts are also simulated. 

11.6.3 Host Interface Simulation 

The simulator simulates the host interface by means of: 

1) A host input file (HIF) that you provide, and 

2) A timing schedule that you provide in the form of a count and a fre¬ 
quency of occurrence selection (given as the number of clock cycles 
between inputs). 

The IH (initiate host) command allows you to initiate and control host inputs 
by selecting, before executing code, the number of inputs and their frequency 
of occurrence. For instance, you could specify that you want a host input to 
occur every 96 clock cycles; the simulator would then generate an input every 
96 clock cycles for the specified number of times. The data in the host input 
file controls the action that the simulator takes at input time. This continues 
until either the count or the data is exhausted. 
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11.6.3.1 Host Input File Layout 

If you want to simulate host inputs, you must first create a host input file 
(HIF). This file is named host.in, according to the conventions described 
by the IH command. Each line of the HIF contains the information needed to 
simulate a single exchange between the TMS34010 and the host. You use the 
IH command to provide the simulator with initial access to the HIF. Access 
to the HIF is driven by the TMS34010 clock and occurs automatically as the 
clock is advanced. 

11.6.3.2 Host Input File Format 

Each line of the HIF contains the HFSO, HFS1, HREAD, and HWRITE pin va¬ 
lues (HCS, chip select, is assumed active). If the operation to be performed 
by the host is a write, the field following the pin values beginning in column 
6 contains the 1 6-bit data value which is to be placed on the HD bus. If the 
host wants to read, then the resulting value on the HD bus is written out to 
the host output file (HOF), host.out with its address and the clock count at 
which the read occurred. The number of times and frequency of occurrence 
of host interrupts is controlled by the interrupt control commands for the 
nonmaskable interrupt. Note that both HIF and HOF are ASCII text files of 
80 columns per record. 

Table 11-1. HIF ASCII Record Format 


Columns 

Info 

Description 

1 

HFSO 

Desired value for HFSO pin (0 or 1). 

2 

HFS1 

Desired value for HFS1 pin (0,1). 

3 

HREAD 

Desired value of HREAD pin (0,1). 

4 

HWRITE 

Desired value of HWRITE pin (0,1). 

5 

xxxxx 

Ignored 

6-9 

HData 

The sixteen bit data word on the HD bus in 
hexadecimal. This data is used only if the 
host is writing to the TMS34010. 

10-80 

don't care 

Information in this block is disregarded - it's 
a good comment area. 


See the IH command for information on how to set up a host input scenario. 
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11.6.4 Graphics Simulation 

The simulator displays graphics on the host screen (depending on mode se¬ 
lection and host configuration) as an offshoot of the TMS34010 local memory 
simulation. 

The default graphics display control parameters (modified using the G com¬ 
mand) are such that TMS3401 0 memory from TMS34010 address 00002000h 
to the end of available screen memory is defined as on-screen and is posi¬ 
tioned in the lower left portion of the host screen. This ensures that the major 
portions of the machine-state display remains free from competing graphics 
display. On systems with interdependent text and graphics, the definition is 
the same except that the on-screen memory is placed in the upper left hand 
corner of the host screen. The default graphics display definition can be re¬ 
called after modification by using the GRI command. 

You can customize the graphics environment for a particular screen config¬ 
uration by using the G command. You can customize the graphics environ¬ 
ment so that large on-screen memory simulation can be brought to the host 
screen by simply redefining the location of the host screen corner within me¬ 
mory. Via the simulator monitor, you can control the origin of the screen, as 
well as the "window" into the screen. The screen, however, is only modified 
when memory is written to or when you invoke the RS (regenerate screen) 
command. 

The maximum graphic display area is determined by the host system. The 
TI-PC 3-plane graphics card displays 720-by-276 pixels. You can select a 
given portion of this screen to view at any one time, and thus simulate a larger 
screen area than the physical device can display at one time. 

On the TI-PC color graphics system, and on all limited display devices, pixel 
values greater than the maximum number of bits per pixel available on the 
display device (3 on the TI-PC) are truncated so that only the LSBs are sig¬ 
nificant. The most significant bits are masked off and the lower bits determine 
the displayed pixel color according to the device color mapping. 

On the TI-PC, then, only pixel sizes of 1 or 2 bits are fully supported, while 
4-bit pixel size still generates a graphic display using the three low-order bits 
of the pixel. Table 11 -2 shows the color mapping for the TI-PC system. 

Table 11-2. TI-PC Color Mapping 


Pixel Value 

Color 

Decimal 

Binary 

0 

xOOO 

Black 

1 

xOOl 

Blue 

2 

xOI 0 

Red 

3 

xO11 

Purple 

4 

xl 00 

Green 

5 

xl 01 

Cyan 

6 

xl 1 0 

Yellow 

7 

xl 1 1 

White 
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11.6.5 DB, DM, and DW Display Comparison 

The simulator provides three commands that allow you to display memory in 
various formats: 

DB displays memory in byte format. 

DM displays memory. 

DW displays memory in word format. 

The displays for each of these instructions are different, as Figure 11 -6 shows. 




(b) DM - Display Memory Command 



(c) DW - Display Word Command 
Figure 11-6. DB, DM, and DW Displays 
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Similarities among the displays include: 

• Each has an 8-digit (32-bit word) address on the left. 

• Each displays the memory values in the center. 

• Each has recognizable ASCII characters on the right. 

The commands differ in the manner in which they display data: 

• The DB command displays data in 8-bit values. 

- The least significant byte is on the left. 

- The most significant byte is on the right. 

The least significant address bit is the rightmost bit (LSB) of the 
first byte displayed (on the left). 

• The DM command displays data in 16-bit words. 

- The least significant byte is on the right. 

- The most significant byte is on the left. 

- The least significant address bit is the rightmost bit on the line. 

• The DW command displays data in 16-bit words. 

The least significant word is on the left. 

- The most significant word is on the right. 

- The least significant address bit is the rightmost bit of the LSW. 

11.6.6 Saving Simulator Status 

You can use one of several commands to save the current TMS34010 simu¬ 
lation state locally or to a file. 

SIO Saves I/O registers. 

SR Saves general-purpose registers. 

RIO Restores I/O registers locally. 

RR Restores registers locally. 

RMI [nnn [offset]] 

Restores a memory image from smifil.nnn applying address off¬ 
set. 

RMS [nnn] 

Restores the machine status from smsfil.nnn. 

SMI start-address end-address [nnn] 

Saves a memory image from vail to val2 in file smifil.nnn. 

SMS [nnn] 

Saves TMS34010 status to file smsfil.nnn. 
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11.7 Demonstration Program 

The simulator disks that are shipped as part of the TMS34010 assembly lan¬ 
guage tools package contain a demonstration program that runs on the simu¬ 
lator. Here are instructions for running the demonstration program. 

1) Invoke the simulator. 

IBM-PC : gspsim CR 
TI-PC : gspsimt CR 

2) Restore the graphics environment. 

The demonstration program was written to run in a specific graphics 
environment. The product disks contain a file that restores this envi¬ 
ronment. Enter: 

Command [0] RGE CR 

This loads the file sgefil.OOO. 

3) Clear the memory that the demonstration program uses. Enter: 

Command [0] F 0 1FFF0 0 CR 

This fills the memory range 0-1 FFFO with Os. 

4) Load thd demonstration program. 

IBM-PC : Command [0] L TUTOR—C. OUT CR 
TI-PC : Command [0] L TUTOR-TI.OUT CR 

5) Now run the program. Enter: 

Command [0] RUN CR 

The demonstration program draws on a simulated screen; the borders of 
this screen are drawn for reference. The simulated screen is limited to a 
size of 256 x 128 pixels; this prevents the graphics demonstration from 
overwriting the machine-state display. 

6) The demonstration program will run until it encounters a software 
breakpoint (trap 29). When this happens, enter a carriage return to 
continue execution. 

The demonstration program illustrates several TMS34010 features. You 
can step through the entire program by entering CR each time the pro¬ 
gram encounters a breakpoint. Alternatively, you can execute a specific 
routine. Table 11-3 lists the program addresses of the routines in the 
demonstration program. 
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Table 11-3. Addresses of Routines in the Demonstration Program 


Address 

Routine 

20320h 

Pixel transfer (PIXT) 

203C0h 

Draw and advance (DRAV) 

20460h 

FILL 

20560h 

Pixel block transfer (PIXBLT) 

207E0h 

Pixel processing options and 
transparency 

20850h 

Windowing 

208F0h 

Text (kerning) 


To run a specific portion of the demonstration program, load the PC with the 
desired address and then enter the RUN command. For example, to run the 
FILL routine, enter the following commands: 

CommandEl]: PC 20460 CR 
Command[1]: RUN CR 

You can use any of the simulator commands to modify or display values while 
the demonstration program runs. This interrupts the program; enter the RUN 
command when you're ready to continue. 


Note: 

To quit execution and leave the simulator, enter Q CR. 
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11.8 Simulator Commands 

Table 11-4 lists according to functional groups. Following Table 11-4, the 
simulator commands are described in alphabetical order. 

Note that command and option abbreviations are indicated by uppercase let¬ 
ters. For example, RUn shows that you can enter this command as RUN or RU. 


Table 11-4. Simulator Command Summary 


Program Execution Commands | 

Command and Syntax 

Operation Description 

CIF 

Close input file 

CLK [value] 

Modify or display clock value 

Help 

Enter help utility 

L filename [offset] 

Load COFF file 

LE 

Display last errors 

LH 

Display last halts 

LM 

Display last monitor messages 

Q[*][C][S] 

Quit simulator 

RC [dock-count] 

Run for specified clock cycles 

REset 

Reset TMS34010 

RUn [instruction-count] 

Run a program 

SS[F][U] [instruction-count] 

Single step through a program, with or without Fast 
update and/or Unassembly options 

SWitch 

Switch command input context 

U [start-address] [end-address] 

Unassemble a program 

Z 

Zero clock counter 

| Register Commands | 

Command and Syntax 

Operation Description 

A 

Display A-file registers 

A/7 [32-bit-value] 

Modify or display an A-file register 

B 

Display B-file registers 

B/7 [32-bit-value] 

Modify or display a B-file register 

CLA 

Clear A-file registers 

CLB 

Clear B-file registers 

CLIO 

Clear I/O registers 

CLR 

Clear both A- and B-file registers 

CTL [16-bit-value] 

Modify or display CONTROL register 

DR 

Display A- and B-file registers 

IO 

Display I/O registers 

IOa? [value] 

Modify specified I/O register 

IV1R register name 

Name a register 

PC [32-bit-value] 

Modify or display program counter 

PM [16-bit-value] 

Modify or display PMASK register 

RIO 

Restore temporary copy of I/O registers 
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Table 11-4. Simulator Command Summary (Continued) 


Register Commands (continued) | 

Command and Syntax 

Operation Description 

RR 

Restore temporary copy of registers 

SIO 

Save temporary copy of I/O registers 

SP [32-bit value] 

Modify or display stack pointer 

SR 

Save temporary copy of registers 

ST [ { {/V|C| V\!} {0\ 1} | 32-bit-value} ] 

Modify or display the status register or specified 
status bit 

| Register Field Manipulation Commands | 

Command and Syntax 

Operation Description 

cd mi}] 

Modify cache disable bit 

CF [{0\1}J 

Modify cache flush bit 

FEO {0\1} 

Modify field extension of field 0 

FE1 {0\1} 

Modify field extension of field 1 

FSO field-size 

Modify field size of field 0 

FS1 field-size 

Modify field size of field 1 

if mi}] 

Modify interrupt enable bit 

ITPVH [5-bit-value 

Modify or display ITPVH bits 

NCZV [4-bit-value 

Modify or display NCZV bits 

pbh mi}] 

Modify or display PBH bit 

pbv mi}] 

Modify or display PBV bit 

pbx mi}] 

Set PBX status bit 

PP [pixel-processing-option] 

Modify or display pixel processing option 

PS [pixel-size] 

Set PSIZE register 

t mi}] 

Toggle transparency bit 

W [{0\1\2\3}] 

Modify or display specified windowing option 

Cache Manipulation Commands | 

Command and Syntax 

Operation Description 

CD f{0\ 1}] 

Modify cache disable bit 

CF [{0\1}] 

Modify cache flush bit 

CLCS 

Clear cache statistics 

DC 

Display cache contents and statistics 

Breakpoint and Trace Commands S 

Command and Syntax 

Operation Description 

BP 

Display existing breakpoints 

BP/7 { C/ear\OFf\ON\Togg/e\Quit} 

Modify existing breakpoints 

B PA{R |W| 11 A} { address | address-pattern} 

Set breakpoint on address 

BPD{R|W|I|A} {data\data-pattern 

Set breakpoint on data 

BPR{R|W|I|A} start-address end-address 

Set breakpoint on range 

CTF 

Close trace file 

TR 

Display existing traces 

TR n [ {C/ear\OFf\ON\Toggle\Quit} ] 

Modify existing traces 

TRA{R |W 1 11A} { address\address-pattern} 

Set trace on address 

TRD{R|W|1|A} {data\data-pattern} 

Set trace on data 

TRR{R|W|I|A} start-address end-address 

Set trace on range 
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Table 11-4. Simulator Command Summary (Concluded) 


| Host and Interrupt Control Commands 1 

Command and Syntax 

Operation Description 

1 

Display current interrupts 

l/i [ { frequency-count \ 

Clear\OFf\0N\Toggfe\Quit } ] 

Modify existing interrupts 

IH count frequency 

Initiate host input 

MT [ OFF {27\28\29} ] 

Modify special traps 

CLS 

Clear the graphics screen 

G 

Customize graphics environment 

GR 

Toggle graphics display 

GR {C/ear\ OFf\ ON\lnit\Disable\Enable} 

Execute graphics option 

RGE [fUe-number-extension] 

Restore graphics environment 

RS 

Regenerate graphics screen 

SGE [file-number-extension] 

Save graphics environment 

TX 

Toggle text display 

| Memory Environment Control Commands | 

Command and Syntax 

Operation Description 

CLM 

Clear simulator memory 

D B start-address [end- address] 

Display bytes 

D M start-address [end-address] 

Display memory 

Dw start-address [end-address] 

Display word of memory 

F start-address end-address 

16-bit-value 

Fill memory with specified word 

FW [start-address end-address] 

16-bit-value 

Find word 

M 

Customize memory environment 

M M [+] address {16-bit- value 1 32 - bit- value | 
assembler-statement} 

Modify or evaluate memory 

MMF[ + ] address field-value field-size 

Modify memory field 

i Machine-State Environment Control Commands | 

Command and Syntax 

Operation Description 

RMI [file-number-extension [offset] ] 

Restore memory image 

RMS [file-number-extension] 

Restore machine state 

SMI start-address end-address 
[file-number-extension ] 

Save memory image 

SMS [fi/e-number-extension] 

Save machine state 

i Debug Environment Control Commands | 

Command and Syntax 

Operation Description 

DE 

Toggle simulator debug mode 

RDE [file-number-extension] 

Restore debug environment 

SDE [file-number-extension] 

Save debug environment 

| Miscellaneous and Special Commands | 

Command and Syntax 

Operation Description 

ID 

Display simulator version identification 

SF filename 

Show file utility 

SY string 

Execute specified system function 

V value 

Evaluate data 
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Display A-File Registers 


A 


Syntax 

Description 

Example 


A 

The A command displays the A- and B-file registers. If the A- and B-file 
registers are already displayed, then the A command clears and rewrites the 
display, providing a full update of the register file contents. 

Display the A- and B-file registers in the machine-state display. 

Command[1] A CR 

Figure 11 -3 (page 11 -5) shows a display that contains the general-purpose 
registers. 
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A n 


Syntax 

Description 


Example 7 

Example 2 


Modify/Display an A-File Register 


An [32-bit-value] 

The An command allows you to modify or display the contents of any of the 
A-file registers. This also allows you to view the contents of an A-file reg¬ 
ister when the text display is off. 

n represents a number from 0-14; the default type for the register number 
is decimal. (To set or inspect the stack pointer, use the SP command.) 

If you provide a 32-bit value, it replaces the value of the specified A-file 
register. If you do not specify a replacement value, the simulator displays 
the current contents of the register. The default type for the value is hexa¬ 
decimal. 

Modify the contents of register A3: 

Command[1] A3 FFFFFFFE CR 

Register A3 now contains the value OFFFFFFFEh. Note that you could 
obtain the same result using the decimal type override, %-2. 

Display the contents of register A3: 

Command[1] A3 CR 
Command[1 ] A3 = FFFFFFFE 

Now the command buffer shows the contents of register A3. 

Note that this form of the command destroys any monitor commands that 
follow in the same buffer. 
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Display B-File Registers 


B 


Syntax 

Description 

Example 


B 

The B command causes the default register display to be the A- and B-file 
registers. If the A- and B-file registers are currently displayed, then the B 
command clears and rewrites the display, providing a full update of the re¬ 
gister file. 

Display the A- and B-file registers in the machine-state display: 

Command[1] B CR 

Figure 11 -3 (page 11 -5) shows a display that contains the general-purpose 
registers. 
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Bn 


Syntax 

Description 


Example 1 

Example 2 


Modify/Display a B-File Register 


Bn [32-bit-value] 

The Bn command allows you to modify or display the contents of any of the 
15 B-file registers. This also allows you to view the contents of an A-file 
register when the text display is off. 

n represents a number from 0-14. The default type for the register number 
is decimal. (To set or inspect the stack pointer, see the SP command.) 

If you specify a 32-bit value , it replaces the value of the specified B-file re¬ 
gister. The default type for the value is hexadecimal. If you do not specify 
a replacement value, the simulator displays the current contents of the reg¬ 
ister. 

Modify the contents of register B3: 

Command[1] B13 FFFFFFFF CR 

Register B13 now contains the value OFFFFFFFFh. Note that you could 
obtain the same result using the decimal type override, %-1. 

Display the contents of register B1 3: 

Command[1] B13 CR 
Command[1] B13 = FFFFFFFF 

The contents of register B13 are now visible in the command buffer. Note 
that this form of the command destroys any monitor commands that follow 
in the same buffer. 


Note: 

The PIXBLT and FILL instructions use register B10-B14. When the 
TMS34010 executes one of these instructions, it does not save values 
the original values in these registers. Be careful that these instructions 
do not destroy data that you have stored in these registers. 
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Display Existing Breakpoints 


BP 


Syntax BP 

Description The BP command displays all existing breakpoints along with their 
active/inactive state. Figure 11-7 illustrates a display typically produced 
by this command. 
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Figure 11-7. Display of Existing Breakpoints 


Each breakpoint has a unique reference number (0 through 19). A combi¬ 
nation of up to 20 breakpoints and traces can be defined. The reference 
numbers shown here are those used in conjunction with the BPa? command 
to manipulate the state of each breakpoint on the list. If a breakpoint is 
inactive, it is displayed with a preceding asterisk. 
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BPn 


Modify Existing Breakpoints 


Syntax 

Description 


Example 7 

Example 2 


BPn [ { Clear \ OFf | ON | Toggle \ Quit } ] 

The BP/? command allows you to modify the status of individual break¬ 
points. A combination of up to 20 breakpoints and traces can be defined. 

n is a breakpoint reference number (0-19) or the letter X. If you specify X 
as the breakpoint number, then all existing breakpoints are affected. The 
breakpoint reference number is displayed when the breakpoint is defined. 
The breakpoint reference number does not change throughout the life of the 
specific breakpoint. The BP command displays the breakpoint numbers. 

Breakpoint options include: 

? Clear 

? destroys the breakpoint. 

OFf deactivates the breakpoint temporarily (but doesn't destroy it). 

An asterisk (*) next to a breakpoint number indicates that the 
breakpoint was deactivated. 

ON reactivates a breakpoint that has been turned off. 

Toggle activates an inactive breakpoint, or deactivates an active break¬ 

point. 

Quit terminates the command without changing any breakpoints. 

Only the significant letters of each option (indicated by the uppercase let¬ 
ters in the list) are processed; CLEAR and C are treated the same. 

If you do not enter the option on the command line, the simulator displays 
the breakpoint and a list of options for you to select from. 

Toggle breakpoint 3: 

Command[1] BP3 T CR 

Clear all breakpoints: 

Command[1] BPX CLEAR CR 
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Modify Existing Breakpoints 


BPn 


Example 3 Enter a breakpoint command without an option: 

Command[1] BP1 CR 

The simulator displays the breakpoint and the following menu: 
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Figure 11-8. Modify Breakpoints Menu 


Now you can enter any of the breakpoint options. For example, you could 
enter T to toggle the breakpoint. This toggles the state of breakpoint 
number 1 to off. Note that breakpoint 1 remains in memory and can be 
reactivated by the same command sequence or by specifying the ON option. 
Alternatively, it can be deleted with the CLEAR option and then overwritten 
by the BPA, BPD, or BPR command. You can verify the modification with 
the BP command. 
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BP Ax 


Set Breakpoint on Address 


Syntax 


Description 


Example 1 


Example 2 


BPAR { address \ address-pattern } 

BPAW { address | address-pattern } 

BPAI { address \ address-pattern } 

BPAA { address | address-pattern } 

The BPA command allows you to set breakpoints, stopping execution at: 

• A specific address or 

• An address that matches a specified address pattern. 

There are four versions of this command: 

BPAR breaks execution on all memory reads from the specified address. 

BPAW breaks execution on all memory writes to the specified address. 

BPAI breaks execution only on instruction acquisitions from the speci¬ 
fied address. 

BPAA breaks execution on all memory accesses to the specified address. 

The default type for the address is hexadecimal. You can use a pattern in¬ 
stead of an address; a pattern is a 32-bit binary number with Is and Os in 
the data compare positions and Xs in the don't care positions. The pattern 
must be enclosed in parenthesis. 

Break execution when the simulator attempts to fetch an instruction from 
location 120FF310h. 

Command[1] BPAI 120FF310 CR 

Break execution on any access to an address that matches the pattern 
XIXX0100XX00XXX0: 

Command[1] BPAA (X1XX0100XX00XXX0) CR 
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Set Breakpoint on Data 


BPDx 


Syntax 


Description 


Example 1 


Example 2 


BPDR { data | data-pattern } 

BPDW { data \ data-pattern } 

BPDI { data | data-pattern } 

BPDA { data | data-pattern } 

This command allows you to set breakpoints, stopping execution when: 

• A specific word of data is accessed or 

• A word of data that matches a specified data pattern is accessed. 
There are four versions of this command: 

BPDR breaks execution on all memory reads of the specified data. 

BPDW breaks execution on all memory writes to the specified data. 

BPDI breaks execution only on instruction acquisitions of the specified 
data. 

BPDA breaks execution on all memory accesses to the specified data. 

The default type for the data is hexadecimal. You can use a pattern instead 
of a word of data; a pattern is a 1 6-bit binary number with 1 s and Os in the 
data compare positions and Xs in the don't care positions. The pattern is 
written within parentheses. 

Break execution on any data word access that matches 120Fh: 

Command[1] BPDA 12OF CR 

Break execution any time a number matching the pattern is read from me¬ 
mory. 

Command[1] BPDR (X1XX0100XX00XXX0) CR 
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BPRx 


Set Breakpoint on Range 


Syntax 


Description 


Example 


BPRR start-address end-address 
BPRW start-address end-address 
BPRI start-address end-address 
BPRA start-address end-address 

This command allows you to set breakpoints, stopping execution on spec¬ 
ified memory accesses within a range of addresses. 

There are four versions of this command: 

BPRR breaks execution on all memory reads of the specified data. 

BPRW breaks execution on all memory writes to the specified data. 

BPRI breaks execution only on instruction acquisitions of the specified 
data. 

BPRA breaks execution on all memory accesses to the specified data. 

The default type for the addresses is hexadecimal. You cannot specify a 
pattern for this command. 

Break execution on any access to locations 4000h through 4120h. The si¬ 
mulator issues a monitor error message if the start address is greater that the 
end address. 

Command[1] BPRA 04000 4120 CR 
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Modify Cache Disable Bit 


CD 


Syntax 

Description 


Example 


CD [ {0 \ 1 } ] 

The CD command allows you to set, reset, or toggle the contents of the CD 
bit. CD is the cache disable bit (bit 1 5 in the CONTROL register): 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

I CD 1 PPOP |PBv|pBH| W I T I RR | RM | reserved | 

CONTROL Register 

The 0 17 parameter is optional; if you do not specify 0 or 1, the command 
toggles the current value of the CD bit. The 0\1 parameter has the follow¬ 
ing effects: 

CD=0 enables the instruction cache. 

CD=1 disables the instruction cache. 

Note that the value of this bit is shown in the machine-state display. 

Set the CD bit to 1 (this disables the cache): 

Command[l] CD 1 CR 
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CF 


Syntax 

Description 


Example 


Modify Cache Flush Bit 


cf noi nj 

The CF command allows you to set or reset the contents of the CF bit. CF 
is the cache flush bit (bit 14 in the HSTCTLFI register): 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 


HLT 

CF 

LBL 

IN 

IN 

res 

NM 

NMI 

reserved 




CR 

CW 


IM 




HSTCTLH Register 

The 0\1 parameter is optional. If you do not specify 0 or 1, the command 
flushes the cache by setting all of the present flags to "not present" and sets 
the cache contents to all Os (this does not affect the CF bit). The 0\1 pa¬ 
rameter has the following effects: 

CF=0 enables cache reads, depending upon the value of the cache dis¬ 
able (CD) bit. 

CF=1 invalidates all current data in the cache. Cache accesses are in¬ 
hibited until the CF bit is set to 0. The cache fragment present 
flags are also cleared. 

Clear the CF bit in the HSTCTL register, enabling cache access: 

Command[1] CF 0 CR 
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Close Input File 


CIF 


Syntax 

Description 

Example 


CIF 

The CIF command closes the opened input file gspinput.000. You can 
restore execution of this file with the SWITCH command. 

If a CIF command is encountered within a batch stream, then the input file 
is closed and execution continues from the beginning of the input file. 
(This produces a continuous loop.) 

Close the input file: 

Command[1] CIF CR 
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CLA 


Clear A-File Registers 


Syntax 

Description 

Example 


CLA 

The CLA command clears (Os) all the A-file registers except the stack 
pointer. (Use the CLR or SP command to clear the stack pointer.) 

Clear registers A0-A14 (SP is not changed). 

Command[1] CLA CR 
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Clear B-File Registers 


CLB 


Syntax 

Description 

Example 


CLB 

The CLB command clears (Os) all the B-file registers except the stack 
pointer. (Use the CLR or SP command to clear the stack pointer.) 

Clear registers B0-B14 (SP is not changed). 

Command[1] CLB CR 
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CLCS 

Syntax 

Description 

Example 


Clear Cache Data/Statistics/Present Flags 


CLCS 

The CLCS command clears the accumulated cache statistics and clears (Os) 
the cache present flags for all four cache segments. In addition, the actual 
cache contents are set to 0 (purged). 

Clear the cache present flags, the cache statics, and the cache contents: 
Command[1] CLCS CR 
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Clear I/O Registers 


CLIO 


Syntax 

Description 

Example 


CLIO 

The CLIO command clears (Os) all of the on-chip I/O registers. To inspect 
the I/O registers or to clear selected I/O registers only, use the 10 command. 

Clear all of the on-chip I/O registers: 

Command[1] CLIO CR 
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CLK 


Modify/Display Clock 


Syntax 

Description 


Example 1 

Example 2 


CLK [value] 

The CLK command allows you to display or modify the contents of the 
simulator clock. The CLK portion of the machine-state display normally 
shows the number of clock cycles consumed during instruction simulation. 
You can use the CLK command to view the clock contents when the ma¬ 
chine-state display is toggled. 

The value is optional; if specified, this becomes the new clock counter va¬ 
lue. The default format for the clock counter is decimal. 

Set the clock count to 100: 

Command [1] CLK 100 CR 

Display the clock count: 

Command [1] CLK CR 
Command [1] CLK = 100 
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Clear Simulator Memory 


CLM 


Syntax 

Description 


Example 


CLM 

The CLM command clears (Os) the entire range of simulator memory, from 
the end of simulator execution space to the end of writable memory. 


Caution: 

CLM clears memory from the end of the simulator's exe¬ 
cution space to the end of writable memory. If this memory 
is used for another purpose, such as a RAM disk, CLM de¬ 
stroys its contents. 


Clear the entire range of available memory: 
Command[1] CLM CR 
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CLR 


Clear A-/B-File Registers and SP 


Syntax 

Description 


Example 


CLR 

The CLR command clears: 

• The A-file registers, 

• The B-file registers, and 

• The stack pointer. 

To clear only the A-file registers, use the CLA command. To clear only the 
B-file registers, use the CLB command. 

Clear all the general-purpose registers and the stack pointer: 

Command[1] CLR CR 
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Clear the Graphics Screen 


CLS 


Syntax 

Description 

Example 


CLS 

The CLS command clears (blanks): 

• The simulated graphics from the host display surface and 

• The scratch display area. 

Clear the screen: 

Command[1] CLS CR 
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CTF 


Close Trace File 


Syntax 

Description 

Example 


CTF 

The CTF command closes the opened trace file named gsptrace. 000. 
This allows you to use the SF (show file) command to inspect a file without 
exiting the simulator. 

Close the trace file: 

Command[1] CTF CR 
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Modify/Display CONTROL Register 


CTL 


Syntax 

Description 


Example 1 

Example 2 


CTL [16-bit-value] 

The CTL command allows you to display or modify the contents of the 
CONTROL register. 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

| CD | PPOP |pBv|pBh[ W | T | RR | RM | reserved] 

CONTROL Register 

The 16-bit value is an optional parameter; its default type is hexadecimal. 
If you do not specify a replacement value, the simulator displays the CON¬ 
TROL register's contents on the command line. This is useful for viewing 
the contents of the CONTROL register when the text display is off. 

Modify the contents of the CONTROL register: 

Command[1] CTL 1046 CR 

Display the contents of the CTL register: 

Command[1] CTL CR 

Command[1] CTL 1046 

CTL 1046 

The contents of the CONTROL register are now visible in the command 
buffer. 

Note that this form of the command destroys any monitor commands that 
follow in the same buffer. 


Note: 

Bits 0 and 1 of the CONTROL register are reserved and cannot be mo¬ 
dified. In these examples, the value in the CONTROL register after ex¬ 
ecution is 1044. 
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DB 


Display Bytes 


Syntax DB start-address [end-address] 

Description The DB command displays blocks of TMS34010 memory. The start address 
and end address are expressed as 32-bit hexadecimal values. 

Example Display a block of memory from address 0200h to 0550h: 

Command[1] DB 200 550 CR 

Although the address specified is a bit address, any bit address portion 
supplied is ignored, and the data is specified in words. The resulting dis¬ 
play is shown below in the default display mode. 
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Figure 11-9. Display Bytes Format 


The simulator can display only 10 lines of information per screen. If you 
request more than 10 lines, the simulator halts the display; enter a carriage 
return to continue the display (see Figure 11-10). Enter a Q to quit the 
display. 
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Display Bytes 


DB 
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Figure 11-10. Display Bytes Format - Over 10 Lines 


Note that the start address must be less than the end address for the DB 
command to operate, or the simulator issues an error message indicating 
that the start of the range exceeds the end. 
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DC 


Display Cache Contents and Statistics 


Syntax DC 

Description The DC command displays the cache contents and statistics on the screen. 

The statistical information is collected only when the cache is enabled. 

Each cache page is displayed in the order of the LRU (least recently used) 
queue. The queue number in the display header refers to the current queue 
number. Queue numbers are displayed in ascending order from 0 to 3. The 
page number in the display refers to the actual cache page number at the 
currently displayed position within the LRU queue. Within each page, 
cache fragments are displayed as four consecutive words. As each in¬ 
struction is encountered, it is disassembled (this is shown on the right side 
of the display). Valid cache fragments that have been loaded by executing 
code are displayed in cyan with yellow stars on the left side. 
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Display Cache Contents and Statistics 


DC 
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Figure 11-11. Cache Contents Display 
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Figure 11-12. Memory Display 


The simulator can display only 10 lines of information per screen. If you 
request more than 10 lines, the simulator halts the display; enter a carriage 
return to continue the display. Enter a Q to quit the display. 

Note that the start address must be less than the end address for the DM 
command to operate, or the simulator issues an error message. 
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Display A-/B-File Registers 


DR 


Syntax D R 

Description The DR command toggles the machine-state display between the I/O reg¬ 
isters and the general-purpose registers. 


Example 1 Display the A- and B-file registers in the machine-state display: 

Command[1] DR CR 
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Figure 11-13. A- and B-File Registers Display 
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DR 


Display A-/B-File Registers 


Example 2 Now display the I/O registers in the machine-state display: 

Command[1] DR CR 
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Figure 11-14. I/O Registers Display 
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Display Words of Memory 


Dw 


Syntax Dw start-address [end-address] 

Description The Dw command displays blocks of TMS34010 memory. The start ad¬ 
dress and end address are expressed as 32-bit hexadecimal values. 

Example Display a block of memory from address 0200h to 0500h: 

Command[1] D 00200 550 CR 

or 

Command[1] DW 00200 550 CR 

Although the addresses are specified as bit addresses, any bit address por¬ 
tion supplied is ignored, and the data is specified in words. The resulting 
display is shown below in the default display mode. 
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Figure 11-15. Display Word Format 


The simulator can display only 10 lines of information per screen. If you 
request more than 10 lines, the simulator halts the display; enter a carriage 
return to continue the display. Enter a Q to quit the display. 

Note that the start address must be less than the end address for the D 
command to operate, or the command line returns with no action. 
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F 


Syntax 

Description 


Example 


Fill Memory with 16-bit Value 


F start-address end-address 16-bit-value 

The F command fills a block of memory from the start address to the end 
address with the specified word value. You can use F to fill screen memory, 
program memory, or both; the simulator does not distinguish between the 
two. 

The start address must be less than the end address. The default type for 
both addresses is hexadecimal. The bit address of both addresses is trun¬ 
cated to form a word address. 

The default type for the 16-bit value is hexadecimal; this parameter specifies 
a fill value. 

You can use the F command to fill screen memory, program memory, or 
both; the simulator does not distinguish between the two. 

Fill memory from 200h to 350h, inclusive, with OOAAh: 

Command[1] F 200 350 AA CR 
F 200 350 AA 
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Modify Field Extension Bits 


FE0/FE1 


Syntax 


Description 


Example 1 


Example 2 


FEO { 0 | 7 } 

FE1 { 0 | 1 } 

The FE command sets the values of the FEO or FE1 bits to select zero- 
extension or sign-extension for field 0 or field 1. The FE bits are the field 
extension bits (bit 5 and bit 11 the status register): 
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Status Register 

The 0\1 parameter has the following effects: 

FE0=0 selects zero extension for field 0. 

FE0=1 selects sign extension for field 0. 

FE1 =0 selects zero extension for field 1. 

FE1 =1 selects sign extension for field 1. 

The FE field in the machine-state display reflects the modifications you 
make with the FE command. 

Set FEO to 1, enabling sign extension for field 0: 

Command[1] FE 0 1 CR 

or 

Command[1] FEO 1 CR 

Modify the contents of the FE1 bit to enable zero extension for field 1: 
Command[1] FEl 0 CR 
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FS0/FS1 


Modify Field Size 


Syntax 


Description 


Example 1 


Example 2 


FSO field-size 
FS1 field-size 

The FS command sets the values of the FSO or FS1 bits to select a new field 
size for field 0 or field 1. The FS bits are the field size bits (bits 0-4 and 
6-10 in the status register): 
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Status Register 


The default type for the field size is a decimal value from 1 to 32. The FS 
field in the machine-state display reflects any modifications you make with 
the FS command. 

Change the field size of field 0 to 16: 

Command [1] FSO 16 CR 

Change the field size of field 1 to 4: 

Command! 1] FS1 4 CR 
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Find Word 


FW 


Syntax FW [start-address end-address] 16-bit-value 

Description The FW command finds a specified 1 6-bit value within a range of memory. 

The simulator displays the value in hexadecimal and decimal, along with the 
address at which it was found. If no value is displayed, then the value was 
not found. 

The default format for the value is hexadecimal. The addresses are specified 
as 32-bit addresses; the default format for the addresses is hexadecimal. 
The addresses must be word aligned; if they are not, then they are forced 
to be word aligned by setting the four LSBs to 0. 


Example Find the value 40h in the range 220h-550h: 

Command[1] FW 220 550 40 CR 

Figure 11-16 shows an example of this command that looks for the word 
value 40 within a defined address range. 
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G 


Customize Graphics Environment 


Syntax G 

Description The G command initializes or modifies the graphics definitions for the 
graphics environment simulation, including screen limits and the pixel size. 
You can use the SGE command to store this data in a file. 


Example Enter the graphics environment customization utility: 

Command[1] G CR 

The simulator displays the screen shown in Figure 11-17. 
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Figure 11-17. Graphics Customization Menu 
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Toggle Graphics Display 


GR 


Syntax 

Description 


Example 


GR 

The GR command and the TX command select between the graphics and 
nongraphics displays. GR toggles the graphics so that the text display can 
be clearly seen. 

On systems with independent graphics display, such as the TI-PC, GR does 
not affect the graphics display. On systems with integrated text and 
graphics, such as the IBM-PC, both the GR and TX commands toggle be¬ 
tween text and graphics. 

TX toggles the text display in the same way that GR toggles the graphics 
display. When the text display is off, the command line remains in its usual 
position, but the simulator status line replaces the previous command entry 
line. 

Turn the graphics display on: Command [1] GR CR 

Command[1] GR 

Normal Stop Mode. 

Note that monitor status messages now appear below the command line: 

Command[1] RUN 

Simulator Running ... 

You can use the same command to toggle the graphics display back off. 
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GRopf 


Execute Graphics Option 


Syntax GR{ CLeaR \ OFF \ ON \ I NIT \ Disable \ ENaBle } 

Description The GR command provides the following options: 

GRCCLR dears the graphics screen of interpreted graphics memory. This 
allows you to clear the screen of graphics display so that only 
newly written graphics data appears on the screen. This does not 
affect the text display. 

GROFF Turn the graphics system off. While the display is off, the graphics 
memory is still being written to, so that when the display is re¬ 
stored, any effect on graphics memory is restored to the screen. 
This command is also useful to view text such as status information 
clearly when the screen is full of graphics information. 

GRON turns the graphics display on 

GRIN IT initializes the graphics system. This returns the graphics environ¬ 
ment to its initial state at invocation, thus returning it to a known 
state. 

GRDIS disables any additional host graphics simulation. This allows the 
simulation to bypass the overhead of interpreting the impact of 
memory accesses on the graphics display, producing a faster func¬ 
tional simulation while the utility of regenerating the screen using 
the RS command remains. However, you do not losed the full, 
concurrent graphics simulation. 

GRENB re-enables the host graphics simulation after it it is disabled. This 
allows additional graphics displays to be routed to the screen. 

The following examples illustrate these functions. 

Example 1 Clear the graphics display. 

Command[1] GRCLR CR 


Command[1] GR CLR CR 

Although the graphics display is cleared, its on/off status is not changed. 


Example 2 Disable host graphics simulation. 

Command[1] GRDIS CR 

or 

Command[1] GR DIS CR 

Although the graphics display is disabled, its on/off status is not changed 
and data displayed on the screen remains. You can restore the display with 
the RS (regenerate screen) command. 
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Execute Graphics Option 


GRopf 


Example 3 


Example 4 


Turn the graphics display on: 

Command[1] GRON CR 
A3 464 

Command[1] GRON 

GRON 


Turn the graphics display off. 

Command[1] GR CR 

A3 464 

Command[1] GR 

GR 
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Help 


Enter Help Utility 


Syntax Help 

Description The HELP command displays a menu of help files. 

When you select a help file, the simulator displays the file in the same 
manner as the SF (show file) command. The simulator informs you if a help 
file is not available. 


Example Display the help menu: 

Command[1] HELP CR 

The simulator enters the help environment and displays a menu that de¬ 
scribes the utility and lists help files for the various classes of commands. 



Figure 11-18. Simulator Help Utility Menu 
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Display Current Interrupts 


Syntax I 

Description The I command displays all currently defined interrupts, including their 
active/inactive status. Figure 11-19 shows a typical display produced by 
the I command. 
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Figure 11-19. Interrupt Displays 


Note that each interrupt is referenced by its level number (0-2, H, 8-11) and 
that any combination of the TMS34010 interrupts can be active at any 
specified time. Interrupt level H is assigned for simulation purposes in the 
host input. 
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In _ 

Syntax 

Description 


Example 1 

Example 2 


Modify Interrupts 


\n [ { frequency-count \ Clear | OFf | ON \ Set | Toggle | Quit } ] 

The 1/7 command allows you to set the status of individual interrupts. (Use 
the I command to display interrupt status.) 


Notes: 

1. If you request a nonexistent interrupt, the command is invalid and 
the simulator issues an error message. 

2. Interrupt priority is preserved during simulation. 


Executing the I command a second time for the same interrupt overwrites 
the previous information for that interrupt. You can also clear, turn off, turn 
on, toggle the interrupt, or quit the command execution. 

The interrupt number (n) corresponds to the number which is specified in 
the I command display. This number is a decimal number 0-2 or 8-11 or 
H. Specifying X as the interrupt number makes the I command apply to all 
the interrupts. Specifying H as the interrupt number refers to host input 
interrupt. 

Generate interrupt INT2 every OFOh clock cycles for a total of three times: 
Command[1] I 2 S FOH 3 CR 

or 

Command[1] 12 S FOH 3 CR 

Clear all interrupts: 

Command[1] IX C CR 
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Modify Interrupts 


1/7 


Example 3 Toggle interrupt 3: 

Command[1] 13 T CR 

or 

Command[1] 13 CR 

The last entry displays the interrupt and the following menu: 
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Figure 11-20. Display Interrupt Options 


At this point, you can enter T. This toggles the state of interrupt number 
2. Note that interrupt 2 remains in memory; you can reactivate it with the 
same command sequence. Alternatively, you can use this same command 
to clear or reinitiate the interrupt. The command entry is verified by the 
display of interrupts exactly as it appears after an I command. 
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ID_ 

Syntax 

Description 

Example 


Identify Simulator Version Number 


ID 

The ID command prints the version of the simulator below the command 
line. 

Display the simulator version number: 

Command[1] ID CR 

Version 1.04120886 
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Modify Interrupt Enable Bit 


IE 


Syntax 

Description 


Example 


IE [{ 0 \ 1 }] 

The IE command allows you to set, reset, or toggle the contents of the IE 
(interrupt enable) bit in the status register. 


3322222222221111111111 

1 098765432 1 0987654321 0987654321 0 
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Status Register 

The 0\1 parameter has the following effects: 

IE=0 disables all maskable interrupts. 

IE=1 enables all maskable interrupts. 

If you do not use the 0\1 parameter, the IE bit is toggled. Note that the 
value of this bit is shown in the I portion of the machine state's ITPVH field. 

Set the IE bit: 

Command[1] IE 1 CR 

This sets the IE bit, which disables interrupts. 


11-71 






IH 


Syntax 

Description 


Example 


Initiate Host Input 


IH count frequency 

The IH command is used in conjunction with a host input file (host, in) 
to simulate the interface between the TMS34010 and a host. You can 
specify how often a host input will occur; count number of host inputs are 
generated every frequency clock cycles. The simulator generates count host 
inputs every frequency clock cycles. If frequency is 0, no host input "in¬ 
terrupts" are allowed; in effect, you are turning host input mode off. By 
default host inputs are disabled. 

When the first host input is generated, the simulator reads the last status 
information from host. in. The information contained in this file represents 
the pin and data bus values the host would ordinarily generate. Also con¬ 
tained in this file is the number of times that each kind of input is to occur. 
Thus, subsequent host input "interrupts" only access the host input file 
when the previously read action information has been completed, 
host, in contains one host input type per line and its format. 

Note that if the host wants to read from the TMS34010, then the value read 
(contained on the HD bus) is written into the host output file, host.out. 
host.out will contain one 16-bit word per line (hexadecimal format), 
along with the clock value at the point at which it occurs. 

Generate a host input 15 times every 150 clock cycles; note that both the 
clock count and frequency are decimal numbers. 

Command[1] IH 150 15 CR 
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Display I/O Registers 


IO 


Syntax 10 


Description The 10 command explicitly sets the default registers in the status display to 
the I/O register. You can use the DR, A, or B commands to to change the 
display between the I/O registers and the A- and B-file registers. 

Example Display the I/O registers in the machine-state display: 

Command[1] 10 CR 
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Figure 11-21. I/O Registers Display 
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IO n 


Modify/Display I/O Register 


Syntax 

Description 


Example 1 

Example 2 


10 n [value] 

The 10 a? command allows you to modify the contents of any of the memo¬ 
ry-mapped I/O registers simply by specifying the offset from the I/O regis¬ 
ter's base address (OCOOOOOOOh). You can also use this command to 
display the contents of a particular I/O register; to do this, use the reference 
number without specifying a replacement value. 

Table 11 -5 lists the I/O registers and their offsets. 

Table 11-5. I/O Registers and Offsets 


Offsett 

Register 

Description 

Offsett 

Register 

Description 

000 

HESYNC 

Horizontal end 
sync 

100 

HSTCTLH 

Host control high 

010 

HEBLNK 

Horizontal end 
blank 

110 

INTENB 

Interrupt enable 

020 

HSBLNK 

Horizontal start 
blank 

120 

INTPEND 

Interrupt pending 

030 

HTOTAL 

Horizontal end 
total 

130 

CONVSP 

Source pitch 

040 

VESYNC 

Vertical end sync 

140 

CONVDP 

Destination pitch 

050 

VEBLNK 

Vertical end blank 

150 

PSIZE 

Pixel size 

060 

VSBLNK 

Vertical start blank 

160 

PMASK 

Plane mask 

070 

VTOTAL 

Vertical total 

170 

- 

Reserved 

080 

DPYCTL 

Display control 

180 

- 

Reserved 

090 

DPYSTRT 

Display start 

190 

- 

Reserved 

0A0 

DPYINT 

Display interrupt 

1 AO 

- 

Reserved 

0B0 

CONTROL 

Control 

1 BO 

DPYTAP 

Display tap 
address 

OCO 

HSTDATA 

Host data 

ICO 

HCOUNT 

Horizontal count 

0D0 

HSTADRL 

Host address low 

IDO 

VCOUNT 

Vertical count 

0E0 

HSTADRH 

Host address high 

1 EO 

DPYADR 

Display address 

0F0 

HSTCTLL 

Host control low 

1 FO 

REFCNT 

DRAM refresh 
count 


t The offset is added to a base address of OCOOOOOOOh. 


Modify the contents of the I/O register located at address OCOOOOOFOh: 

Command[1] 10 FO F046 CR 

The HSTCTLL register now contains 0F046h. 

Inspect the contents of the FISTCTLL register: 

Command[1] 10 FO CR 

Command[1] 10 FO = F046 
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Modify/Display ITPVH Bits 


ITPVH 


Syntax 

Description 


Example 1 

Example 2 

Example 3 


ITPVH [5-bit-value] 

The ITPVH command allows you to display or modify the contents of the 
ITPVH bits, found in the status and CONTROL registers: 

I Interrupt enable bit (status bit 21) 

T Transparency bit (CONTROL bit 5) 

P PixBIt executing bit (status bit 25) 

V PixBIt vertical bit (CONTROL bit 9) 

H PixBIt horizontal bit (CONTROL bit 8) 

1514 13 12 11 10 9 8 7 6 5 4 3 21 0 

| CD | PPOP [PBV|PBH| W | T | RR | RM | reserved [ 

CONTROL Register 


3 

1 

3 

0 

2 

9 

2 

8 

2 2 
7 6 

2 

5 

2 2 2 
4 3 2 

2 

1 

2 11111111 
098765432 

1 

1 

1 

0 9 8 7 6 

5 

4 3 2 1 0 






P 


1 


F 


F 


N 

C 

Z 

V 

res 

B 

res 

E 

res 

E 

FS1 

E 

FS0 






X 




1 


0 



Status Register 

To modify any of the bits, enter a 5-bit value composed of Os and Is. A 
value of 1 sets the bit; a value of 0 clears the bit. 

To display the current contents of these bits, enter the command without 
any value. 

Reset the ITPVH bits to Os: 

Command [0] ITPVH 00000 CR 

Display the values of the ITPVH bits: 

Command [0] ITPVH CR 
Command [0] ITPVH = 00000 

Enable interrupts and turn transparency on: 

Command [0] ITPVH 11000 CR 
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L 


Syntax 

Description 


Example 1 


Example 2 


Load File 


L filename [offset] 

The L command loads a linked, executable COFF module into the simulator 
local memory so that it can be executed. You can use the optional offset 
parameter to relocate the module at load time. Note that the simulator 
cache is flushed on a successful load so that old code in cache is not exe¬ 
cuted. 

The filename names the module that is loaded into memory. You can spe¬ 
cify a file without an extension; .out is the default extension for modules 
produced by the linker and .obj is the default extension for modules pro¬ 
duced by the assembler. If you do not specify an extension for filename, 
the simulator first attempts to load filename. If this file isn't found, the 
simulator attempts to load filename.out. If this file isn't found, the si¬ 
mulator attempts to load filename.obj. You can load unlinked code, but 
the simulator issues a warning message, and unresolved references are not 
resolved. 

If you specify an offset, then the simulator attempts to relocate the module 
when loading by adding the offset to all relocation entries in the module. 
The offset is treated as a signed 32-bit quantity. If you attempt to load an 
absolute (nonrelocatable) module, the simulator issues a warning and ig¬ 
nores the offset . If you do not specify an offset, then all relocation entries 
are loaded relative to 0. 

The graphics display is inhibited to speed the load. Data loaded into de¬ 
fined screen memory does not appear on the graphics display. You can use 
the RS command to see the graphic interpretation of the loaded data. 

Load module code.out with offsets 0 and lOOODOOh, respectively: 

Command[1] L CODE CR 

Command[1] L CODE.OUT 1000D00 CR 

The second example above causes the simulator to open and read the file 
code.out, interpret it, and load it into the simulated TMS34010 memory 
with an offset of lOOODOOh. 

Load a COFF file from the directory \laser\out on drive C: 

Command[0] L C:\LASER\OUT\CODE CR 
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Display Last Errors 


LE 


Syntax 

Description 

Example 


LE 

The LE command displays the most recent set of error messages after they 
are removed from the screen. Error messages appear in red in the scratch- 
display. 

Display previous error messages: 

Command[1] LE CR 
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LH 


Syntax 

Description 

Example 


Display Last Halts 


LH 

The LH command displays the most recent set of halt messages after they 
are removed from the screen. Halt messages, which are generated by en¬ 
countering breakpoints, appear in cyan in the scratch-display. 

Display previous halt messages: 

Command[1] LH CR 
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Display Last Monitor Messages 


LM 


Syntax 

Description 

Example 


LM 

The LM command displays the most recent set of monitor error messages 
after they are removed from the screen. Monitor error messages appear in 
yellow in the monitor-message display. 

Display previous monitor messages: 

Command[1] LM CR 
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M 


Customize Memory Environment 


Syntax M 

Description The M command initializes or modifies the memory definitions for the sim¬ 
ulation. The memory values that can be modified are the general and the 
screen memory limits. You can use the SGE command to store this data 
along with the graphics environment information. 


Example Command [ 1 ] M CR 

The simulator displays the menu shown in Figure 11 -22. This menu allows 
you to selectively modify the memory environment. 


Graphics Environment Customisation Commends 
M ~~ set Mamory Begin and End B set H/W WfndoW‘s BImans 

& ~~ set Screen Memory Begin Gr — set Window's C3P position 

. P set Screen Memory Pitch H — set HQst Display Dimension 
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Figure 11-22. Graphics Environment Menu 


Selecting either the S or G menu allows you enter changes for each of these 
values. Entering a carriage return instead of a value leaves the value un¬ 
changed. 
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Modify/Evaluate Memory 


MM 


Syntax 

Description 


Example 1 


address { 16-bit-value | 32-bit-value | assembler-statement} 

The MM command allows you to modify or interrogate memory. The ad¬ 
dress is specified by a 32-bit address. The default format of the address is 
hexadecimal. The address must be word aligned; if it is not, the simulator 
word-aligns it by setting the four LSBs to 0. 

The second parameter is optional and can be: 

• A 16-bit value, 

• A 32-bit value , or 

• A line of TMS34010 assembler code. 

The default format for the value parameters is hexadecimal. The default for 
values specified by assembler code is hexadecimal, except for the TRAP, 
SETF, and K instructions. If you follow the command with the optional + 
symbol, the simulator increments the address by the size of the data you 
enter. 

If you do not use a value parameter, then the command reports on the 
contents of the memory location. The address is displayed in hexadecimal, 
decimal, and as an XY address. The contents of the word at the address in 
memory are also displayed as hexadecimal, decimal, and as a disassembled 
instruction. 

Use the command to report on a memory location. Assume the following 
initial conditions: 

Memory location 0FF0 contains 2980h 

CONVSP = 1 5h 

CONVDP - 16h 

OFFSET - 0 

PSIZE = 4 

Command[1] MM FF8 CR 

This example produces the display shown in Figure 11 -23. 
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MM 


Modify/Evaluate Memory 
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Figure 11-23. Modify Memory Display 


This form of the command overwrites any trailing commands on the com¬ 
mand line; trailing commands are not executed. You can use this command 
to find equivalent linear addresses from XY addresses, although the V 
command is also provided for this purpose. 

Example 2 Use the MM command to modify a memory location: 

Command [1] MM FF8 FEC4 CR (1 6-bit value) 

Command [ 1 ] MM FF8 1FEC4 CR (32-bit value) 

Command [ 1 ] MM FF8 move A0,B9 CR (Assembler code) 

Each of these examples changes the value of the word or words starting at 
address 0FF8h to the type of value on the right. Note that a 16-bit value 
or 32-bit value is specified indirectly by the number of hexadecimal digits 
required to hold the result: 

• FEC4 is a 16-bit value 

• 1 FEC4 is a 32-bit value. 

You can force a hexadecimal value to be a 32-bit value by using leading 
Os. The value 0FEC4 is a 32-bit value. Values specified with a decimal 
format override take up as much space as required to hold the hexadecimal 
equivalent, but leading Os are not taken into account. For negative num¬ 
bers, the space is calculated for the positive equivalent. Thus, -1 is a 16-bit 
value. 

Specifying a line of assembler code modifies as many words as it takes for 
the opcode and its operands to be placed in memory. This can be as many 
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Modify/Evaluate Memory 


MM 


as five words. All values in the assembler code specification must be nu¬ 
meric values as opposed to symbolic. For address relative instructions, the 
value is specified as the address. The line assembler calculates the relative 
offset for you. Except for the requirement that values cannot be symbolic, 
the syntax of assembly code for the line assembler is the same as described 
in the assembly language section. 

Note that if the graphics display is enabled and the memory location is in 
screen memory and is in the host window, you may see a change in the 
graphics display. The change in memory is treated in the same way as if it 
had been done through program execution. 
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MMF 


Modify Memory Field 


Syntax 

Description 


Example 


MMF/>/ address field-value field-size 

The MMF command modifies memory on not necessarily word-aligned 
boundaries using a specified field size. The address is specified by either a 
32-bit bit address or an XY address. The default format of address is hex¬ 
adecimal. The second parameter, field value, is a field of one to 32 bits. 
The default format for field value is hexadecimal. The value for field size is 
from one to 32. The default format for field size is decimal. If you follow 
the command with the optional + symbol, the simulator increments the 
address by the size of the data you enter. 

Modify a memory field: 

Command[1] MMF FF8 F 4 CR 
Command[1] MMF FF8 %100 7 CR 
Command[1] MMF FF8 1 1 CR 

Each of these examples changes the value of the field starting at address 
0FF8h to the value on the right. If the specified field value is larger than the 
field size, then the low order bits up to the field size are inserted. That is, 
the LSBs of the value are placed into the field in memory. 

Note that if the graphics display is enabled and the memory location is in 
screen memory and is in the host window, you may note a change in the 
graphics display. The change in memory is treated in the same way as if it 
had been done through program execution. 
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Modify Special Traps 


MT 


Syntax MT [{ OFF | { 27 \ 28 \ 29 } }] 

Description The MT command modifies the simulator's treatment of the three special 
traps: 

27 converts TMS34010 address for use by the simulator's print utility. 

28 uses the simulator's PRINTF utility. 

29 terminates execution and return to the simulator's user level. 

The optional OFF parameter turns off the processing of all the special traps; 
they are then treated as normal traps. The specification of the optional trap 
number turns the specified special trap back on. Yon can only specify one 
of the three special traps listed above. If you do not supply any parameter, 
then the simulator displays the status of the three special traps. 

Figure 11-24 illustrates the MT display. 
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Figure 11-24. Modify Special Traps Display 
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NCZV 


Modify/Display NCZV Bits 


Syntax 

Description 


Example 1 

Example 2 


NCZV [4-bit-value] 

The NCZV command allows you to display or modify the contents of the 
NCZV status bits. 

N sign bit (status bit 31) 

C carry bit (status bit 30) 

Z zero bit (status bit 29) 

V overflow bit (status bit 28) 


3 

1 

3 

0 

2 

9 

2 

8 

2 2 
7 6 

2 

5 

2 2 2 
4 3 2 
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2 11111111 
098765432 

1 

1 

1 
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FSO 






X 




1 


0 



Status Register 


To modify any of the bits, enter a 4-bit value composed of Os and Is. To 
display the current contents of these bits, enter the command without any 
value. 

Set the sign bit to 1 and the other bits to Os: 

Command [0] NCZV 1000 CR 

Display the contents of the NCZV bits: 

Command [0] NCZV CR 
Command [0] NCZV = 1000 
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Name Register 


NR 


Syntax 

Description 


Example 1 

Example 2 


N R register name 

The NR command allows you to assign a name to any of the general- 

purpose registers or the stack pointer. 

• The register parameter can be A0-A14, B0-B14, or SP. 

• The name is a 1 - to 6-character alternate name for the register. The 
register name is used in the machine-state display in reverse assem¬ 
blies (it appears next to the register in the screen display). It cannot 
work with the register-value exchange designation. 

Designate register AO as SUM: 

Command [1] NR AO SUM CR 

SUM can now be substituted for AO. Also, in reverse assemblies, SUM is 

used instead of AO (for example, move A4,A0 appears as move A4,sum). 

To delete SUM as the name for AO, enter: 

Command [1] NR AO CR 
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PBH/PBV 


Toggle PBH or PBV Bits 


Syntax 


Description 


Example 


PBH [{ 0 | 1 }] 

PBV [{ 0 | 1 }] 

These commands allow you to set, reset, or toggle the PBH or PBV bit to 
select the horizontal and vertical directions for PIXBLTs. The PBH and PBV 
bits are the PIXBLT horizontal and vertical direction bits (bit 8 and bit 9 in 
the CONTROL register): 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

| CD | PPOP |PBV|PBH| W | T | RR | RM | reserved | 

CONTROL Register 

The optional 0\1 parameter has the following effects: 

PBH=0 increment X (move from left to right) 

PBH=1 decrement X (move from right to left) 

PBV=0 increment Y (move from top to bottom) 

PBV=1 decrement Y (move from bottom to top) 

If you do not use the 011 parameter, then the selected bit is toggled. Note 
that the value of both of these bits are shown in the the machine-state 
display as the H and V bits in the ITPVH field. 

Set the PBV bit: 

Command[1] PBV 1 CR 

This sets the PBV bit to 1, which causes PIXBLT instructions to decrement 
in the Y direction. If you then enter: 

Command[1] PBV CR 

This toggles the PBV bit, which causes PIXBLT instructions to increment 
in the Y direction. 
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Set PBX Status Bit 


PBX 


Syntax 

Description 


Example 


PBX [{ 0 | 1 }] 

The PBX command allows you to set, reset, or toggle the PBX bit. The PBX 
bit is the PixBIt executing bit (bit 25 in the status register): 
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Status Register 

The optional 0\1 parameter has the following effects: 

PBX=0 PIXBLT execution is not resumed after an interrupt. 

PBX=1 PIXBLT execution is resumed after an interrupt. 

If you do not specify a 0 or a 1, the value of the PBX bit is toggled. Note 
that this bit is displayed in the ITPVH field of the machine-state display. 

Set the PBX bit to 1: 

Command [1] PBX 1 CR 

This causes an RETI instruction to resume execution of a PixBIt instruction. 
Of course, if a PixBIt instruction was not in progress, then unpredictable 
results occur. If you then enter: 

Command [1] PBX CR 

This toggles the PBX bit back to 0, so that any interrupted PIXBLT is not 
resumed. 
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PC 


Modify/Display Program Counter 


Syntax 

Description 


Example 1 

Example 2 


PC [32-bit-value] 

The PC command allows you to modify or display the contents of the pro¬ 
gram counter. If you use the optional 32-bit value, then the simulator re¬ 
places the contents of the PC with this value. The default type for the 
replacement value is hexadecimal. 

Note that the PC always contains a word aligned value; that is, the lower 4 
bits are 0. If the value is not word aligned, the simulator word-aligns it by 
truncating its lower 4 bits truncated to 0 before loading it into the PC. 

If you do not specify a new value for the PC, the simulator displays the 
current contents of the PC. 

Modify the contents of the PC: 

Command[1] PC 4302 CR 

The PC now contains the value 00004300h. Note the truncation of the 
lower 4 bits of the value. 

Display the contents of the PC from the command line by using the com¬ 
mand without specifying a value: 

Command[1] PC CR 
Command[1] PC = 00004300 

The contents of the PC are now visible in the command buffer. This is 
useful for viewing the contents of the PC while the text display is off. Note 
that this form of the command destroys any monitor commands that follow 
in the same buffer. 
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Modify/Display PMASK Register 


PM 


Syntax 

Description 


Example 1 


Example 2 


PM [16-bit-value] 

The PM command allows you to modify or display the contents of the 
PMASK register. If you specify a 16-bit value, the simulator replaces the 
conentes of the PMASK register with this value. The default type for the 
value is hexadecimal. 

If you do not specify a new value for the PMASK register, the simulator 
displays the current contents of the PMASK register. 

Modify the contents of the PMASK register: 

Command[1] PM FFFE CR 

The PMASK register now contains the value OFFFEh. This value allows 
only the LSB of each word written during graphics instructions to be af¬ 
fected. 

Display the contents of the PMASK register from the command line: 

Command[1] PM CR 
Command[1] PM = FFFE 

The contents of the PMASK register are now visible in the command buffer. 
This is useful for viewing the contents of the PMASK register while the text 
display is off. Note that this form of the command destroys any monitor 
commands that follow in the same buffer. 
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pp 


Syntax 

Description 


Modify/Display Pixel Processing Option 


PP [pixel-processing-option] 

The PP command allows you to modify or display the contents of the PPOP 
bits. The PPOP bits are the pixel-processing option bits (bits 10-14 in the 
CONTROL register): 

1514 13 12 11 10 9 8 7 6 5 4 3 21 0 

| CP 1 PPOP |PBv|pBH| W | T | RR I RM I reserved I 

CONTROL Register 

If you specify a pixel processing option, the simulator stores this value in 
the PP bits. The default type for the pixel processing option is decimal. 

If you do not specify a new pixel processing option, the simulator displays 
the current pixel processing option. 

Table 11 -6 lists valid pixel processing options. 

Table 11-6. Pixel Processing Options 


PP Bits 

Operation 

Description 

0 

S -+ D 

Replace destination with source 

1 

S AND D -+D 

AND source with destination 

2 

S AND D ->D 

AND source with NOT destination 

3 

0 -> D 

Replace destination with Os 

4 

SORDID 

OR source with NOT destination 

5 

S XNOR D -D 

XNOR source with destination 

6 

D -*D 

Negate destination 

7 

S NOR D ->D 

NOR source with destination 

8 

SORDID 

OR source with destination 

9 

D -> D 

No change in destination 

10 

S XOR D ->D 

XOR source with destination 

11 

S AND D D 

AND NOT source with destination 

12 

1 -► D 

Replace destination with Is 

13 

SORDID 

OR NOT source with destination 

14 

S NAND D ->D 

NAND source with destination 

15 

S D 

Replace destination with NOT source 

16 

D + S D 

Add source to destination 

17 

D ADDS S -> D 

Add source to destination with 
saturation 

18 

D - S -> D 

Subtract source from destination 

19 

D SUBS S -> D 

Subtract source from destination with 
saturation 

20 

D MAX S -> D 

Maximum of source and destination 

21 

D MIN S -> D 

Minimum of source and destination 
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Modify/Display Pixel Processing Option 


PP 


Example 1 


Example 2 


Modify the contents of the PP bits: 

Command[1] PP 10 CR 

The PP bits now contain the value 10. 

Display the contents of the PP bits from the command line: 

Command[1] PP CR 
Command[1] PP = 10 

The contents of the PP bits are now visible in the command buffer. This is 
useful for viewing the contents of the PP bits while the text display is off. 
Note that this form of the command destroys any monitor commands that 
follow in the same buffer. 
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PS__ 

Syntax 

Description 


Example 1 


Example 2 


Modify/Display PSIZE Register 


PS [pixel-size] 

The PS command allows you to modify or display the contents of the PSIZE 
register. If you specify a replacement pixel size, then the simulator replaces 
the contents of the PSIZE register with the new pixel size. The default type 
for the pixel size is decimal. 

If you do not specify a new pixel size, the simulator displays the current 
contents of the PSIZE register. 

Modify the contents of the PSIZE register: 

Command[1] PS 8 CR 

The PSIZE register now contains the value 8. This value causes the simu¬ 
lator to process pixels at a size of 8 bits per pixel. Note that the only valid 
values for the pixel size are 1,2, 4, 8, and 16. If you specify any other value, 
the simulator will issue an error message. 

Display the contents of the PSIZE register from the command line: 

Command[1] PS CR 
Command[1] PS = 8 

The contents of the PSIZE register are now visible in the command buffer. 
This is useful for viewing the contents of the PSIZE register while the text 
display is off. Note that this form of the command destroys any monitor 
commands that follow in the same buffer. 
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Quit Simulation 


Q 


Syntax 

Description 


Example 


Q[*][C][S] 

The Q command terminates the simulator session. 

When you execute the Q command, the simulator asks if you are sure that 
you want to terminate the session. If you answer yes, then all files that the 
simulator has opened are closed and the simulator terminates execution. 

You can use three parameters with this command, singly or in combination. 

* The simulator does not ask you to verify termination. This is useful if 
you are running the simulator as part of a batch stream and you do not 
want any keyboard inputs. (See also the -f option.) 

C The simulator clears the screen of both text and graphics on exit. 

S The simulator executes the equivalent of the save machine state com¬ 
mand with no parameters; that is, the machine state is saved to the file 

smsfile.000. 

Terminate the simulator session: 

Command[1] Q CR 

ARE YOU SURE? [Y/N]: 
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RC 


Syntax 

Description 


Example 


Run for Clock Cycles 


RC [dock-count] 

The RC command begins execution of memory resident TMS34010 code. 
If you specify a dock count, then the simulator executes instructions until 
the timing clock has progressed dock count number of cycles; at this point, 
the simulator returns control to the monitor. If you do not specify a dock 
count, or if you specify 0 as the dock count, then the execution is free run 
and is equivalent to the RUN command with no run count. The default type 
for the count is decimal. 

You can prematurely terminate the execution by typing a character from the 
keyboard. Execution also halts if a breakpoint is encountered or if an exe¬ 
cution error occurs. Execution will not halt in the middle of an instruction, 
except for instructions that are interruptible (such as the PixBIt in¬ 
structions); therefore, the timing clock is usually not incremented by exactly 
dock count number of cycles when execution terminates. 

Execute code and halt at the nearest interruption point after 1000 (decimal) 
clock cycles: 

Command[1] RC 1000 CR 
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Restore Debug Environment 


RDE 


Syntax 

Description 


Example 1 

Example 2 


RDE [file-number-extension] 

The RDE command restores the saved debugging environment from a file 
in the default directory. You can use the RDE command in conjunction 
with the SDE (save debug environment) command to restore the following 
from a saved debugging environment context: 

• Traces 

• Breakpoints 

• Register names 

• Command buffers 

If you do not specify a file number extension , then the restoration file is 
called smsf il. 000. 

If you do specify a file number extension, then the simulator converts it to 
the ASCII of its decimal representation and fills it with zeros on the left to 
form a 3-character file extension. This limits the file number extension to 
0-999, inclusively. The simulator uses this 3-character extension to form 
the filename smsf il. nnn, where nnn is the 3-character file extension. The 
default type for the file number extension is decimal. 

To restore a specific debugging environment via the RDE command, you 
must specify the same file number extension that it was saved with. See the 
SDE command for more information. 

Restore the debugging environment from data stored in the file 

sdefil.042: 

Command[1] RDE 42 CR 

Restore the debugging environment from data stored in the default file 

sdefil.000: 

Command [1] RDE CR 
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REset 


Simulate TMS34010 Reset 


Syntax 

Description 

Example 


REset 

The REset command performs a simulated reset of the TMS34010 via a 
monitor command. This initializes the program counter with the contents 
of trap vector 0, sets the status register to 10h, sets all 10 registers to 0, re¬ 
moves all pending interrupts, and clears the cache. 

Command[1] RE CR 

or 

Command[1] RESET CR 
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Restore Graphics Environment 


RGE 


Syntax 

Description 


Example 1 

Example 2 


RGE [file-number-extension] 

The RGE command restores the simulated graphics environment from a file 
in the default directory. You can use the RGE command in conjunction 
with the SGE (save graphics environment) command to restore a previously 
saved graphics environment context. 

If you do not specify a file number extension, then the restoration file is 
called smsfil.OOO. 

If you do specify a file number extension, then the simulator converts it to 
the ASCII of its decimal representation and zero fills it on the left to form a 
3-character file extension. This limits the file number extension to 0-999, 
inclusively. The simulator uses this 3-character extension to form the fi¬ 
lename smsfil.nnn, where nnn is the 3-character file extension. The 
default type for the file number extension is decimal. 

To restore a specific graphics environment via the RGE command, you must 
specify the same file number extension that it was saved with. The SGE 
command discusses saving the graphics environment. 

The graphics environment saved via the SGE command includes the general 
memory beginning and ending values, the screen memory beginning and 
ending values, the TMS34010 upper left screen origin, and other elements 
described by the G command. 

Restore the graphics environment from data stored in the file sgef il. 042: 
Command[1] RGE 42 CR 

Restore the graphics environment from data stored in the default file sge- 
f il. 000: 

Command[1] RGE CR 


11-99 




RIO 


Restore Temporary Copy of I/O Registers 


Syntax 

Description 

Example 


RIO 

The RIO command restores the contents of the I/O registers from a copy 
that is kept in simulator local memory (as opposed to on disk). The copy 
of the I/O registers should have been save previously with the SIO (save 
I/O registers) command. If the registers were not saved previously, RIO 
sets them to 0. 

Restore the local copy of the I/O register: 

Command[1] RIO CR 
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Restore Memory Image 


RMI 


Syntax 

Description 


Example 1 

Example 2 

Example 3 


RMI [file-number-extension [offset] ] 

RMI restores the region of TMS34010 memory that was previously saved 
with the SMI command. You can use the RMI command in conjunction 
with the SMI (save memory image) command to restore a range of memory 
that were previously saved in a disk file. Note that the beginning and end¬ 
ing addresses of the memory image have been stored in the file along with 
the memory data, and need not be specified. 

If you do not specify a file number extension, then the restoration file is 
called smsfil.OOO. 

If you do specify a file number extension, then the simulator converts it to 
the ASCII of its decimal representation and zero fills it on the left to form a 
3-character file extension. This limits the file number extension to 0-999, 
inclusively. The simulator uses this 3-character extension to form the fi¬ 
lename smsfil.nnn, where nnn is the 3-character file extension. The 
default type for the file number extension is decimal. 

You can offset the memory image from its present location in memory by 
specifying an offset parameter. The default type for the offset is hexadeci¬ 
mal. Note that the offset is treated as a signed 32-bit value. If you specify 
an offset, then you must also specify a file number extension. 

To restore a specific memory image via the RMI command, you must specify 
the same file number extension that it was saved under. The simulator tells 
you if the file does not exist. If the simulator reaches a premature end-of- 
file condition on the smifi! or if it encounters a memory write error, then the 
data restored thus far from the file to memory remains in memory. In both 
cases, the simulator will inform you of the incomplete memory restoration. 
See the SMI command for saving the memory image. 

Restore the memory image data stored in the file smif il. 100: 

Command[1] RMI 100 CR 

Restore the memory image data stored in the file smif il. 047, offsetting 
the data in memory by a value of 0401 h bits: 

Command[1] RMI 47 0401 CR 

Restore the memory image data stored in the default file smif il. 000: 
Command[1] RMI CR 

You could also use the default with an offset, as shown below (780h is the 
offset): 

Command[1] RMI 0 780 CR 
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RMS 


Restore Machine State 


Syntax 

Description 


Example 1 

Example 2 


RMS [file-number-extension] 

You can use the RMS command in conjunction with the SMS (save ma¬ 
chine state) command to restore a machine state of the simulator from a 
disk file in the default directory. The machine-state elements restored in¬ 
clude: 

• General-purpose registers 

• I/O registers 

• Status register 

• PC 

• Clock 

• Trap vectors 

If you do not specify the file number extension, then the restoration file is 
called smsfil.OOO. 

If you do specify a file number extension, then the simulator converts it to 
the ASCII of its decimal representation and zero fills it on the left to form a 
3-character file extension. This limits the file number extension to 0-999, 
inclusively. The simulator uses this 3-character extension to form the fi¬ 
lename smsfil.nnn, where nnn is the 3-character file extension. The de¬ 
fault type for the file number extension is decimal. 

To restore a specific graphics environment via the RMS command, you 
must specify the same file number extension as with which it was saved. 
The simulator informs you if the restoration file does not exist. The SMS 
command discusses saving the machine state. 

Restore the machine-state data in the file smsfil. 100: 

Command[1] RMS 100 CR 

Restore the machine-state data stored in the default file smsfil. 000: 
Command[1] RMS CR 
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Restore Temporary Copy of Registers 


RR 


Syntax 

Description 

Example 


RR 

The RR command restores the contents of the A- and B-file registers from 
a copy that is kept in simulator local memory (as opposed to on disk). The 
copy of the registers should have been saved previously with the SR (save 
registers) command. If the registers were not previously saved then the si¬ 
mulator sets them to 0. 

Restore the local copy of the A- and B-file registers: 

Command[1] RR CR 
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RS_ 

Syntax 

Description 


Example 


Regenerate Graphics Screen 


RS 

The RS command regenerates the picture information from the screen me¬ 
mory. This is useful when you have changed the value of any of the pa¬ 
rameters that affect the way in which memory is interpreted to the display 
screen. These parameters include: 

• Hardware pixel size, 

• Screen memory start and end, 

• The displayable window into screen memory, 

• Host window start and end, host window location on the display 

screen, and 

• Host window dimensions. 

You can change these parameters with the G command. 

Since the screen regeneration may take a substantial amount of time, de¬ 
pending upon the number of display screen pixels that are affected, the si¬ 
mulator asks you if you are sure that you want to continue. This command 
can also be invoked in the G command. 

Regenerate the screen from data supplied via the G command, or indirectly 
via the RGE command. 

Command[1] RS CR 
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Run a Program 


RUn 


Syntax 

Description 


Example 1 


Example 2 


RUn [instruction-count] 

The RUn commands executes instructions either continuously or until a 
specified instruction count is reached. The screen display is not updated 
until execution is halted. You can enter the command as RUN or abbreviate 
it as RU. 

If you specify an instruction count, the simulator executes instruction count 
number of instructions and then return control to the command line. The 
default type for the instruction count is decimal. If you do not specify an 
instruction count , the simulator executes instructions until: 

• You halt execution with a keystroke, 

• An error is encountered, 

• A breakpoint is encountered, or 

• A TRAP 29 is executed. 

You can use the MT command to disable the halt on TRAP 29. 

Execute the RUN command with an instruction count of 100: 

Command[1] RUN 100 CR 

or 

Command[1] RU 100 CR 

Execution halts after 100 instructions if none of the halt conditions men¬ 
tioned above have occurred. 

Execute the RUN command without an instruction count: 

Command[1] RUN CR 

or 

Command[1] RU CR 

Execution halts only if one of the halt conditions mentioned above has oc¬ 
curred. 

Also see the RC, SS, BP, and MT commands. 
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SDE 


Save Debug Environment 


Syntax 

Description 


Example 1 

Example 2 


SDE [file-number-extension] 

The SDE command saves the current simulator debugging environment to 
a file in the default directory. Debugging elements that are saved include: 

• Traces 

• Breakpoints 

• Register names 

• Command buffers 

You can use the RDE command to restore the saved debug environment. 

If you do not specify a file number extension, then the file is called sde- 
fil.000. 

If you do specify a file number extension, the simulator converts it to the 
ASCII of its decimal representation and zero fill it on the left to form a 
3-character file extension. This limits the file number extension to 0-999, 
inclusively. The simulator uses this 3-character extension to form the file 
name sdefil.nnn, where nnn is the 3-character file extension. The de¬ 
fault type for the file number extension is decimal. 

To restore a specific debug environment via the RDE command, you must 
specify the same file number extension as with which it was saved. 

Save the debugging environment in the file sdefil.043: 

Command[1] SDE 43 CR 

Save the debugging environment in the default file sdef il. 000: 

Command[1] SDE CR 
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Show File Utility 


SF 


Syntax 

Description 


Example 


SF filename 

The SF command displays the contents of a file (specified by filename) to 
the screen. This allows you to access system files without corrupting or 
losing the current simulation. The simulator clears the screen before and 
after displaying the file. 

If the specified file is longer than 23 lines, the simulator displays 23 lines 
and pause until the you enter a carriage return. If you want to halt the 
display, enter a Q. 

This command is useful for displaying assembly listing and linker map files 
during a debugging session. 

Display the contents of the file example. 1st: 

Command[1] SF EXAMPLE.LST CR 
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SGE 


Save Graphics Environment 


Syntax 

Description 


Example 1 

Example 2 


SGE [file-number-extension] 

The SGE command saves the simulated graphics environment to a file in the 
default directory. The graphics elements saved by the SGE command in¬ 
clude: 


• General memory starting and ending values 

• Screen memory starting and ending values 

• Upper left screen origin 

You can use the RGE command to restore a saved graphics environment. 

If you do not specify a file number extension, then the file is called sge- 
f il. 000. If you do specify a file number extension, the simulator converts 
it to ASCII of its decimal representation and zero fills it from the left to form 
a 3-character file extension. This limits the file number extension to 
0-999, inclusively. The simulator uses this 3-character extension to form 
the file name sgefil.nnn, where nnn is the 3-character file extension. 
The default type for the file number extension is decimal. 

To restore a specific graphics environment via the RGE command, you must 
specify the same file number extension that is was saved under. 

Save the graphics environment in the file sgefil.043: 

Command[1] SGE 43 CR 

Save the graphics environment in the default file sgefile.000: 

Command[1] SGE CR 
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Save Temporary Copy of I/O Registers 


SIO 


Syntax 

Description 

Example 


SIO 

The SIO command saves the contents of all of the I/O registers to a copy 
that is kept in simulator local memory (as opposed to on disk). Note that 
this is temporary memory and is cleared between invocations of the simu¬ 
lator. You can restore the I/O registers by using the RIO (restore I/O reg¬ 
isters) command. 

Save a local copy of the I/O registers: 

Command[1] SIO CR 
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SMI 


Save Memory Image 


Syntax 

Description 


Example 1 

Example 2 

Example 3 


SMI start-address end-address [file-number-extension] 

You can use the SMI command to save a range of memory to disk. The SMI 
command saves the region of TMS34010 memory from the start address to 
the end address in binary format in a file on disk in the default directory. 
The default format for both addresses is hexadecimal. 

The RMI command restores the memory image. 


Note: 

The addresses specified for the SMI command are inclusive bit ad¬ 
dresses. Thus, if you specify the starting and ending addresses as the 
same address, then a single bit is saved. If you want to save all of the 
words of memory from 0 up to and including the word starting at 400h, 
then the starting and ending addresses should be 0 and 40Fh. If you 
specify 400h as the ending address, then only the first bit of the word 
at 400h is saved. 


If you do not specify a file number extension, then the save file is called 

smif il. 000. 

If you do specify a file number extension, the simulator converts it to the 
ASCII of its decimal representation and zero fill it from the left to form a 
3-character file extension. This limits the file number extension to 0-999, 
inclusively. The simulator uses this 3-character extension to form the file 
name smifil.nnn, where nnn is the 3-character file extension. The de¬ 
fault type for the file number extension is decimal. 

If the save file cannot be created or there is an error while writing to the file 
(running out of disk space), the saving of memory to the file terminates and 
the file is closed. If you attempt to restore the memory image in the file, 
then whatever was stored in the file up to the error is restored. The RMI 
command then detects a premature end of file on the restoration file and 
signals an error. 

To restore a specific graphics environment via the RMI command, you must 
specify the same file number extension that it was saved under. See the 
RGE command for restoring the graphics environment. 

You can use the SMI command to preserve a specified memory context for 
debugging or to store screen data. 

Save the memory image data from address 1 AOh to 200Fh in the file smi- 
f il. 792. The data is stored in noncompressed, binary-image format. 

Command[1] SMI 1A0 2OOF 792 CR 

Save a single bit of memory at 1A1 h in the file smif il. 003. The %3 in¬ 
dicates a decimal 3. Since the default type for the extension is decimal, the 
%3 is equivalent to 3. 

Command[1] SMI 1A1 1A1 %3 CR 

Save the memory image data from address 440Ch to 4601 h in default file 

smifil.000: 

Command[1] SMI 440C 4601 CR 
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Save Machine State 


SMS 


Syntax 

Description 


Example 1 

Example 2 


SMS [file-number-extension] 

The SMS command saves the machine state to a file in the default directory. 
Machine-state elements that are saved include: 

• General-purpose registers 

• I/O registers 

• Status register 

• Program counter 

• Clock 

• Trap vectors 

You can use the RMS command to restore the saved machine state. 

If you do not specify a file number extension, then the save file is called 

smsfil.000. 

If you specify a file number extension, the simulator converts it to the ASCII 
of its decimal representation and zero fills it on the left to form a 3-character 
file extension. This limits the file number extension to 0-999, inclusively. 
The simulator uses this 3-character extension to form the file name 
smsf il. nnn, where nnn is the 3-character file extension. The default type 
for the file number extension is decimal. 

To restore a specific graphics environment via the RMS command, you 
must specify the same file number extension that it was saved under. The 
RMS command discusses restoring the machine state. 

Save the status data in the file smsfil. 100: 

Command[1] SMS 100 CR 

Save the machine-state data in the default file smsfil.000: 

Command[1] SMS CR 
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SP_ 

Syntax 

Description 

Example 1 

Example 2 


Modify/Display Stack Pointer 


SP [32-bit-value] 

The SP command modifies or displays the contents of the stack pointer re¬ 
gister. If you specify the optional 32-bit value , this value replaces the 
contents of the stack pointer. The default type for this value is hexadecimal. 
(To modify or display the A- and B-file register, see the An and B n com¬ 
mands.) 

Modify the contents of the stack pointer: 

Command[1] SP 4000 CR 

The SP register now contains the value 00004000h. 

Display the stack pointer contents from the command line: 

Command[1]SP CR 
Command[1] SP = 00004000 

The contents of the SP register are now visible in the command buffer. This 
is useful for viewing the contents of the SP register while the text display 
is off. Note that this form of the command destroys any monitor commands 
that follow in the same buffer. 
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Save Temporary Copy of Registers 


SR 


Syntax 

Description 

Example 


SR 

The SR command saves the contents of the A- and B-file registers in a copy 
that is kept in the simulator local memory (as opposed to on disk). You can 
restore the registers from the copy by using the RR (restore registers) 
command. Note that you can only save one copy of the registers at a time; 
reinvoking the SR command overwrites the registers that were previously 
saved. 

Save a copy of the A and B registers: 

Command!1] SR CR 
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ss_ 

Syntax 

Description 


Example 1 

Example 2 

Example 3 


Single Step through Program 


SS [instruction-count] 

SSF [instruction-count] 

SSU [instruction-count] 

SSFU [instruction-count] 

The SS command allows you to single step through a program for in¬ 
struction count number of instructions, with or without Fast update and/or 
Unassembly. 

If none of the optional parameters, including F and U, are specified, then 
the simulator executes only one assembly language instruction and then 
updates the machine-state display. If you specify the optional instruction 
count, then the simulator executes that number of instructions and com¬ 
pletely updates the machine-state display after executing each instruction. 

The F and U options allow you to select a fast update or an unassembly: 

• A Fast update is used when stepping for a number of instructions. 
The F option inhibits the update of the simulator machine-state dis¬ 
play after each instruction except the last. This is functionally equiv¬ 
alent to the RUN command with an instruction count, but executes 
slightly slower. 

• An Unassembly provides a 5-line reverse-assembly after each in¬ 
struction. The reverse-assembly includes information about the two 
previous program counter locations, the current program counter lo¬ 
cation, and the two following locations. The display is similar to that 
of the U command. 

You can use the F and U options together to provide a faster single step 
with unassembly. 

Single step for one instruction: 

Command[1] SS CR 

Single step for 10 instructions: 

Command[1] SS 10 CR 

Use the F and U options: 

Command[1] SSF CR 
Command[1] SSFU 100 CR 
Command[1] SSU 10 CR 

Note that you can use the F, U, and instruction count options independ¬ 
ently or in conjunction with one another. 

Also see the RC, RUN, MT, and BP commands. 
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Modify/Display the Status Register 


ST 


Syntax 

Description 


Example 1 

Example 2 


Example 3 


ST [{{N\C\V\Z}{0\1} \ 32-bit-value}] 

The ST command allows you to modify or display the contents of the status 
register by specifying either: 

• A status bit name and a value for that bit or 

• A 32-bit value to replace the entire contents of the ST. (The default 
type for this value is hexadecimal.) 
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Status Register 


You can also selectively set or reset the contents of the N (sign), C (carry), 
Z (zero), and V (overflow) status bits by specifying the bit's letter name and 
the desired value. Note that the values of these bits are shown in the NCZV 
field of the machine-state display. 

You can also use ST to display the contents of the status register from the 
command line by using the command without specifying a value. This is 
useful for viewing the contents of the status register when the text display 
is off. 

Modify the contents of the status register using a 32-bit value: 

Command[1] ST F0000046 CR 

Turn on the Z bit of the status register: 

Command[1] ST Z 1 CR 

Note that the space after ST is optional when specifying a particular status 
bit; it is allowed for clarity. 

To turn off the Z bit, enter: 

Command[1] STZ 0 CR 

Display the contents of the status register: 

Command[1] ST CR 
Command[1] ST = F0000046 

The contents of the status register are now visible in the command buffer. 
Note that this form of the command destroys any monitor commands that 
follow in the same buffer. 
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SWITCH 


Switch Command Input Context 


Syntax 

Description 


Example 


SWitch 

The SWITCH command modifies the command entry source from the key¬ 
board to the file gspinput. 000. Commands are accepted as they occur in 
the file until a SWITCH command is encountered in the file or an EOF is 
encountered. At this point, control returns to the keyboard. 


Note: 

If the SWITCH command is interrupted before completing the com¬ 
mand string (for example, an unexecutable command is encountered) 
and terminates with an error message, the string can be continued at 
the command after the one in error by issuing another SWITCH com¬ 
mand. If you instead want to begin with the first command in the file, 
first enter the CIF command. 


When the SWITCH command is encountered in the file, the simulator re¬ 
turns to accepting its input from the keyboard. If you enter another 
SWITCH command, then the simulator accepts input from the file, contin¬ 
uing where it had previously left off in reading the file. If an EOF is en¬ 
countered then the input file is closed. Another SWITCH command will 
then begin reading again from the top of the file. You can also cause the 
simulator to automatically begin reading from the input file by specifying 
the S option when the simulator is invoked. 

Switch the command input source: 

Command[1] SWITCH CR 

Figure 11 -25 shows a sample input file. 


re 

ssu 13 
bpaa 13 
rc 1200 
switch 


Figure 11-25. gspinput.000 Example File 

Note that the file contents are automatically converted to uppercase. 
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Execute System Function 


SY 


Syntax 

Description 


Example 


SY string 

The SY command executes MS-DOS system functions from the simulator. 
You can use SY to edit, assemble, link, copy files, and perform other func¬ 
tions without exiting the simulator session. 


Caution: 

The simulator does not protect your local memory when ex¬ 
ecuting system commands. You should save any nonrecov- 
erable memory contents with the SMI command before 
executing a system command. 


Command[1] 

or 

Command[1] 

or 

Command[1] 

or 

Command[1] 

or 

Command[1] 


SY COPY \GSP_ASM\HELLO.OBJ HELL02.OBJ CR 

SY gspasm \gsp_asm\hello.obj CR 

SY edit \gsp_asm\hello.asm CR 

SY cd \gsp—asm CR 

SY dir B: CR 


The simulator machine-state display is cleared and the MS-DOS command 
is executed. After the command is complete, the simulator waits for a car¬ 
riage return before clearing the screen and rebuilding the simulator ma¬ 
chine-state display. Normal system control characters affect the execution 
in the same manner as if the command were invoked from the operating 
system. 


11-117 





T 


Toggle Transparency Bit 


Syntax 

Description 


Example 


T [{0 | 1}] 

The T command sets, resets, or toggles the contents of the T bit. The T bit 
is the transparency bit (bit 5 in the CONTROL register): 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

| CD | PPOP |pBv|pBh| W 1 T | RR | RM | reserved [ 

CONTROL Register 

The 0\1 parameter is optional; if you do not specify 0 or 1, the command 
toggles the current value of the T bit. The 0\1 parameter has the following 
effects: 

T=0 disables transparency. 

T=1 enables transparency. 

Note that the value of this bit is shown in the ITPVH field of the ma¬ 
chine-state display. 

Set the T bit: 

Command[1] T 1 CR 

The T bit is set to 1, enabling transparency. 

If you then enter: 

Command[1] T CR 

the T bit is toggled back to 0, disabling transparency. 
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Display Existing Traces 


TR 


Syntax TR 


Description The TR command displays all existing traces, along with their 
active/inactive state. 

Each trace is assigned a reference number. You can define a combined 
maximum of 20 traces and breakpoints at one time. The reference numbers 
specified here are those that are used in conjunction with the TR/? com¬ 
mand to manipulate the state of each trace in the list. Traces are defined 
and modified using the commands described in the following sections. 

Figure 11 -26 shows an example of this display. 
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Figure 11-26. Display of Existing Traces 
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TR/7 


Modify Existing Traces 


Syntax 

Description 


Example 1 


TR n [ { Clear \ OFf | ON | Toggle | Quit } ] 

The TRa? command modifies the status of individual traces. The n parameter 
specifies a specific trace. This number is a decimal integer between 0 and 
19 or the letter X If you specify X as the trace number, then all existing 
traces are affected. You can define a combination of up to 20 traces and 
breakpoints. The trace reference number is displayed when the trace is de¬ 
fined, and can be viewed with the TR command. Once you have assigned 
certain trace conditions to a trace number, the number is associated only 
with those conditions until you clear the specific trace. 

You can use the following options with the traces: 

Clear Destroys the trace. 

OFf Deactivates the trace temporarily but does not destroy it. 

ON Reactivates deactivated traces. 

Toggle Toggles the current state of a trace. If the trace is deactivated, T 
reactivates it; if the trace is activated, T deactivates it. 

Quit Terminates the command without making any changes. 

Only the significant letters of an option (indicated by upper case letters in 
the preceding list) are processed. This allows you to specify a shorthand 
version of the option. For example. Clear and C are treated the same. If you 
do not enter the option on the command line, then a menu is displayed and 
you are allowed to select the desired option from the menu. 

Toggle trace 3: 

Command[1] TR3 TOG CR 

or 

Command[1] TR3 CR 

The second entry causes the simulator to display the trace and the menu 
shown in Figure 11 -8. 
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Modify Existing Traces 


TRn 



At this point, you can enter T to toggle the state of trace number 3 to off. 
Note that trace 3 remains in memory; you can reactivate it with the same 
command sequence or specify the ON option. Alternatively, you can delete 
it with the Clear option, and then overwrite it with the TRA, TRD, or TRR 
commands. The simulator verifies the changes you make to a trace by dis¬ 
playing the trace and its associated conditions in the scratch area. 

Example 2 Clear all traces: 

Command[1] TRX CLEAR CR 
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TRAx 


Set Trace on Address 


Syntax TRAR { address | address-pattern } 

TRAW { address \ address-pattern } 

TRAI { address | address-pattern } 

TRAA { address | address-pattern } 

Description The TRA command sets traces to stop execution when the simulator ac¬ 
cesses: 

• A specified address or 

• An address that matches a specified address pattern. 

There are four versions of this command: 

TRAR breaks on all memory reads from the specified address. 

TRAW breaks on all memory writes from the specified address. 

TRAI breaks on instruction acquisition from the specified address. 
TRAA breaks on all memory accesses to the specified address. 

The default type for the address is hexadecimal. 

You can use a pattern instead of an address; specify a pattern as a 32-bit 
binary number with Is and Os in the data compare positions and Xs in the 
don't care positions. You must enclose the pattern in parentheses. 

Example 1 Figure 11-28 shows a trace when the simulator fetches from location 
120FF31Oh: 
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Figure 11-28. Trace on Address Display 
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Set Trace on Address 


TRAx 



Figure 11-29. Trace on Address Pattern Display 
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TRDx 


Set Trace on Data or Pattern 


Syntax TRDR { data | pattern } 

TRDW { data | pattern } 

TRDI { data | pattern } 

TRDA { data | pattern } 

Description The TRD command sets traces to stop execution when the simulator ac¬ 
cesses: 

• A specified word of data or 

• A specified data pattern. 

There are four versions of this command: 

TRDR breaks on all memory reads of the specified data. 

TRDW breaks on all memory writes of the specified data. 

TRDI breaks on instruction acquisition of the specified data. 

TRDA breaks on a!i memory accesses of the specified data. 

The default type for the data is hexadecimal. 

You can use a pattern instead of a word of data; specify the pattern as a 
16-bit binary number with Is and Os in the data compare positions and Xs 
in the don't care positions. You must enclose the pattern within parenthe¬ 
sis. 

Example 1 Figure 11 -30 shows a trace on any memory access to data word 120Fh. 
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Figure 11-30. Trace on Data Display 
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Set Trace on Data or Pattern 


TRDx 


Example 2 


Figure 11 -31 shows a trace on memory reads when the data pattern 
matches XIXX01 00XX00XXX0: 
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Figure 11-31. Trace on Pattern Display 
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TRRx 


Set Trace on Range 


Syntax TRRR start-address end-address 

TRRW start-address end-address 
TRRI start-address end-address 
TRRA start-address end-address 

Description The TRR command sets traces to stop execution when the simulator ac¬ 
cesses memory within a range of addresses. There are four versions of this 
command: 

TRRR breaks on all memory reads in the range. 

TRRW breaks on all memory writes in the range. 

TRRI breaks on instruction acquisitions in the range. 

TRRA breaks on ail memory accesses in the range. 

The start address and end address specify the starting and ending points 
of the address range. The end address must be greater than the start ad¬ 
dress, or the simulator issues an error message. Their default type is hexa¬ 
decimal. 



Example Figure 11-32 shows a trace on any memory access within in the rage 

40000h to 41 20h: 
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Figure 11 >32. Trace on Range Display 
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Toggle Text Display 


TX 


Syntax 

Description 


Example 


TX 

The TX command toggles the text display (including the simulator ma¬ 
chine-state display) so that the graphics display can be clearly seen. Only 
the command line and the line below it are displayed. 

On systems with independent graphics display, such as the TI-PC, the TX 
command does not affect the graphics display. On systems with integrated 
text and graphics, such as the IBM-PC, both of the TX and GR commands 
toggle between text and graphics. 

In the same way that the TX command toggles text on and off, the GR 
command toggles the graphics display on and off. When the text is display 
off, the command line remains at the bottom of the screen and the simulator 
status line replaces the previous command entry on the following line. 

Note that when you toggle back to text mode, the scratch-display area is 
cleared. 

Toggle the text display. 

Command[1] TX CR 

Command!1] TX 

Normal Stop Mode. 

The monitor status messages now appear below the command line: 

Command!1] RUN 

Simulator Running ... 

You can toggle the text back on by repeating the TX command. 
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Unassemble (Reverse-Assemble) 


Syntax U [start-address] [end-address] 

Description The U command unassembles (reverse-assembles) blocks of memory, de¬ 
pending on whether: 

• No addresses are specified, 

• Only a start address is specified, or 

• Both a start address and an end address are specified. 

The simulator can display up to nine instructions at one time. If the speci¬ 
fied block contains more than nine instructions, enter a carriage return to 
display the next block of nine instructions. 

Example 1 Unassemble without specifying an address: 

Command[1] U CR 

Figure 11 -33 illustrates this example. The display shows reverse assemblies 
of: 

• The last two program counter locations, 

• The current program counter location, and 

• The next two instructions following the current PC. 
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Figure 11-33. Reverse-Assembly Display 
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Unassemble (Reverse-Assemble) 


U 



Figure 11-35. Reverse-Assembly within a Range of Addresses Display 
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V 


Evaluate Data 


Syntax V value 

Description The V command displays a specified value in several formats: 

• The simulator first displays the value as if it were an address. 

• Next, the simulator displays the contents of the memory word at the 
address specified by the value. (Note that the lower four bits of the 
value are ignored, since it is treated as a word address.) 

• The third line displays the hexadecimal and decimal representations 
of the value. 

The default format for the value parameter is hexadecimal. The size of value 

can be up to 32 bits. 


Example Figure 11 -36 shows an example of the V command. Assume the following 

initial conditions: 

Memory location OFFO contains 2980h 

CONVSP - 15h 

CONVDP - 16h 

OFFSET = 0 

PSIZE = 4 
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Figure 11-36. Evaluate Data Display 
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Select Windowing Option 


W 


Syntax 

Description 


Example 1 

Example 2 


W [{1 \2\3\4}] 

The W command sets the window option bits (bits 6 and 7 in the CON¬ 
TROL register). 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

| CD | PPOP |PBV|PBH| W 1 T | RR | RM | reserved] 

CONTROL Register 

Setting the W bits to a value of 1, 2, 3, or 4 selects one of the following 
window options: 

W=0 No windowing. Writes to any pixel are allowed with no interrupts. 

W=1 Pick function. Pixel writes are inhibited, and an attempt to write 
within the window generates an interrupt. 

W=2 Pixel writes within the window are allowed. An attempt to write 
outside the window generates an interrupt. 

W=3 Pixel writes outside the window are inhibited, but no interrupts are 
generated. 

The W field of the machine-state display shows the current windowing 
option. If you enter the W command and do not select a windowing option, 
the simulator displays the current windowing option. 

Modify the contents of the W field: 

Command[1] W 2 CR 

Display the contents of the W field from the command line: 

Command[1] W CR 
Command[1] W 2 

The contents of the W field of the CONTROL register are visible in the 
command buffer. 
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z_ 

Syntax 

Description 

Example 


Clear Clock Counter 


z 

The Z command clears the clock counter (sets it to 0). You can enter the 
Z command to clear the clock counter at any time during the simulator 
session. Note that zeroing the clock counter affects interrupts and the host 
input because they both key on the clock count. Therefore, after clearing 
the clock count you should recreate any interrupts or host inputs. 

Clear the clock counter in the TMS34010 machine-state display: 

Command[1] Z CR 
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Appendix A 

Common Object File Format 


The TMS34010 assembler and linker create object files that are in common 
object file format (COFF). COFF is an implementation of an object file format 
of the same name that was developed by AT&T for use on UNIX-based sys¬ 
tems. This object file format is used because it encourages modular pro¬ 
gramming and provides more powerful and flexible methods for managing 
code segments and target system memory. 

One of the basic COFF concepts is sections. Section 3, Introduction to 
Common Object File Format, discusses COFF sections in detail. If you un¬ 
derstand section operation, you will be able to use the TMS34010 assembly 
language tools more efficiently. 

This appendix contains technical details about COFF object file structure. 
Much of this information pertains to the symbolic debugging information that 
is produced by the C compiler. The main purpose of this appendix is to pro¬ 
vide supplementary information for those of you who are interested in the in¬ 
ternal format of COFF object files. 


Topics in this appendix include: 


Section Page 

A.1 File Structure.A-2 

A.2 File Header .A-4 

A.3 Optional File Header .A-5 

A.4 Section Headers .A-6 

A.5 Relocation Information .A-8 

A.6 Line Number Table .A-10 

A.7 Symbol Table .A-12 
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Appendix A - COFF File Structure 


A.1 File Structure 

The elements of a COFF object file describe the file's sections and symbolic 
debugging information. These elements include: 

• A file header, 

• Optional header information, 

• A table of section headers, 

• Raw data for each initialized section, 

• Relocation information for each initialized section, 

• Line number entries for each initialized section, 

• A symbol table, and 

• A string table. 

The assembler and linker produce object files with the same COFF structure; 
however, a program that is linked for the final time does not usually contain 
relocation entries. Figure A-1 illustrates the overall object file structure. 


File Header 
Optional File Header 
Section 1 Header . 

♦ 


Section n Header 



.ga.w Data 

faction T 


* 

Section n. 

R elo cation information 
Section 1 

_Une .Numbers_ 

• 

♦ 

Section n 
Une Numbers 


Symbol Table 


String Table 


> 




> 


Section Headers 


Raw Data 
(executable code 
and initialized data) 


Relocation Information 


Line Number 
Entries 


Figure A-1. COFF File Structure 
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Appendix A - COFF File Structure 


Figure A-2 shows a typical example of a COFF object file that contain the 
three default sections, .text, .data, and .bss and a named section (referred to 
as <named>). By default, the .text, .data, and .bss sections, respectively, are 
placed in the object file, followed by any named sections in the order in which 
they were encountered. Although uninitialized sections (created with the .bss 
and .usect directives) have section headers, they have no raw data, relocation 
information , or line number entries. This is because the .bss and .usect di¬ 
rectives simply reserve space for uninitialized data; uninitialized sections con¬ 
tain no actual code. 
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Figure A-2. Sample COFF Object File 
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Appendix A - File Header 


A.2 F 


le Header 

The file header contains 20 bytes of information that describe the general for¬ 
mat of an object file. Table A-1 shows the structure of the file header. 


Table A-1. File Header Contents 


Byte 

Number 

Type 

Description 

0-1 

Unsigned short integer 

Magic number (090h), indicates that the file 
can be executed in a TMS34010 system 

2-3 

Unsigned short integer 

Number of section headers 

4-7 

Long integer 

Time and date stamp, indicates when the file 
was created 

8-11 

Long integer 

File pointer, contains the offset of the sym¬ 
bol table's starting address from the begin¬ 
ning of the file 

12-15 

Long integer 

Number of entries in the symbol table 

16-17 

Unsigned short integer 

Number of bytes in the optional header. 
This field is either 0 or 28; if it is 0, then 
there is no optional file header. 

18-19 

Unsigned short integer 

Flags (see Table A-2) 


Table A-2 lists the flags that can appear in bytes 18 and 1 9 of the file header. 
Any number and combination of these flags can be set at the same time (for 
example, if bytes 18 and 19 are set to 0003h, then F—RELFLG and F—EXEC 
are both set.) 


Table A-2. File Header Flags (Bytes 18 and 19) 


Mnemonic 

Flag 

Description 

F—RELFLG 

0001 h 

Relocation information was stripped from 
the file 

F-EXEC 

0002h 

The file is relocatable (it contains no unre¬ 
solved external references) 

F-LNNO 

0004h 

Line numbers were stripped from the file 

F-LSYMS 

001 Oh 

Local symbols were stripped from the file 

F-QR32WR 

0040h 

The file has the byte ordering used by the 
TMS34010 (16 bits per word, least signif¬ 
icant byte first) 
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A.3 Optional File Header 

The linker creates the optional file header and uses it to perform relocation at 
download time. Partially linked files do not contain optional file headers. 
Table A-3 illustrates the optional file header format. 


Table A-3. Optional File Header Contents 


Byte 

Number 

Type 

Description 

0-1 

Short integer 

Magic number (01 08h for TMS34010) 

2-3 

Short integer 

Version stamp 

4-7 

Long integer 

Size (in bits) of executable code 

8-11 

Long integer 

Size (in bits) of initialized bits 

12-15 

Long integer 

Size (in bits) of uninitialized data 

16-19 

Long integer 

Entry point 

20-23 

Long integer 

Beginning address of .text 

24-27 

Long integer 

Beginning address of .data 
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Appendix A - Section Headers 


A.4 Section Headers 

COFF object files contain a table of section headers that specify where each 
section begins in the object file. Each section of the file has its own section 
header. A section is padded so that its size is a multiple of two bytes. 

Table A-4. Section Header Contents 


Byte 

Number 

Type 

Description 

0-7 

Character 

Eight-character section name, padded with 
nulls 

8-11 

Long integer 

Section's physical address 

12-15 

Long integer 

Section's virtual address 

16-19 

Long integer 

Section size in bits (multiple of 16) 

20-23 

Long integer 

File pointer to raw data 

24-27 

Long integer 

File pointer to relocation entries 

28-31 

Long integer 

File pointer to line number entries 

32-33 

Unsigned short integer 

Number of relocation entries 

34-35 

Unsigned short integer 

Number of line number entries 

36-37 

Unsigned short integer 

Flags (see Table A-5) 

38 

Character 

Reserved 

39 

Character 

Memory page number 


Table A-5 lists the flags that can appear in bytes 36 and 37 of the section 
header. 


Table A-5. Section Header Flags (Bytes 36 and 37) 


Mnemonic 

Flag 

Description 

STYP-REG 

OOOOh 

Regular section (allocated, relocated,loaded) 

STYP-DSECT 

0001 h 

Dummy section (not allocated, relocated, not loaded) 

STYP-NOLOAD 

0002h 

Noload section (allocated, relocated, not loaded) 

STYP-GROUP 

0004h 

Grouped section (formed from several input sections) 

STYP-PAD 

0008h 

Padding section (not allocated, not relocated, loaded) 

STYP-COPY 

001 Oh 

Copy section (relocated, loaded, but not allocated; relo¬ 
cation and line number entries are processed normally) 

STYP-TEXT 

0020h 

Section contains executable code 

STYP-DATA 

0040h 

Section contains initialized data 

STYP-BSS 

0080h 

Section contains uninitialized data 

STYP-ALIGN 

OlOOh 

Section is aligned on a cache boundary 


Note: The term loaded means that the raw data for this section appears in the object file 


The flags listed in Table A-5 can be combined; for example, if the flags field 
(bytes 36 ane 37) is set to 024h, then STYP-GROUP and STYP-TEXT are 
both set. 
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Figure A-3 illustrates how the pointers in a section header would point to the 
various elements in an object file that are associated with the .text section. 


.text 
Section Header 


0-7 


8-11 12-15 16-19 20-23 24-27 28-31 32-33 34-35 36-37 38 39 


.text 


•t ext • • 
Raw Data 


.text 


.text 

Line Numbers ; 


Figure A-3. An Example of Section Header Pointers for the .text Section 


As Figure A-2 (page A-3) shows, uninitialized sections (created with the .bss 
and .usect directives) vary from this format. Although uninitialized sections 
have section headers, they have no no raw data, no relocation information, 
no line number information, and occupy no actual space in the object file. 
Therefore, the number of relocation entries, the number of line number entries, 
and the file pointers are 0 for an uninitialized section. The section header 
simply tells the linker how much memory it should reserve for variables. 
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A.5 Relocation Information 

A COFF object file has one relocation entry for each relocatable reference. The 
assembler automatically generates relocation entries. The linker reads the re¬ 
location entries as it reads each input section and performs relocation. The 
relocation entries determine how references within each input section are 
treated. 

The relocation information entries use the 10-byte format shown in Table A-6. 

Table A-6. Relocation Entry Contents 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Virtual address of the reference 
in the section 

4-5 

Unsigned short integer 

Symbol table index (0-65535) 

6-7 

Unsigned short integer 

Reserved 

8-9 

Unsigned short integer 

Relocation type (see Table A-7) 


• The virtual address is the symbol's address in the current section be¬ 
fore relocation; it specifies where a relocation must occur. (This is the 
address of the field in the object code that must be patched.) 

Here's an example of code that generates a relocation entry: 

0001 .global X 

0002 00000000 0D5F CALLA X 

00000010 00000000 ! 

In this example, the virtual address of the relocatable field is lOh. 

• The symbol table index is the index into the symbol table of the relo¬ 
catable symbol that is referenced. In the preceding example, this field 
would contain the index of x into the symbol table. The amount of the 
relocation is the difference between the symbol's current address in the 
section and its assembly-time address. The relocatable field must be 
relocated by the same amount as the referenced symbol. In the example, 
x has a value of 0 before relocation. Suppose x is relocated to address 
2000h. This is the relocation amount (2000h - 0 = 2000h), so the re¬ 
locatable field at address lOh is patched by adding 2000h to it. 

You can determine a symbol's relocated address if you know which 
section it is defined in. For example, if x is defined in .data, and .data is 
relocated by 2000h, then x is also relocated by 2000h. 

If the symbol table index ina relocation entry is -1 (OFFFFh), this is 
called an internal relocation. In this case, the relocation amount is simply 
the amount that the current section is being relocated. 

• The relocation type specifies the size of the field to be patched and 
indicates how the patched value should be calculated. The type field 
depends on the addressing mode that was used to generate the relocat¬ 
able reference. In the preceding example, the actual address of the ref- 
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erenced symbol (x) will be placed ina 32-bit field in the object code. 
This is a 32-bit direct relocation, so the relocation type is 
R—RELLONG. Table A-7 lists the relocation types. 


Table A-7. Relocation Types (Bytes 8 and 9) 


Mnemonic 

Flag 

Relocation Type 

R-ABS 

OOOOh 

No relocation 

R-RELWORD 

001 Oh 

16-bit direct 

R-RELLONG 

0011h 

32-bit direct 

R—OCRLONG 

0018h 

1 's complement 32-bit direct 

R—GSPPCR16 

001 9h 

16-bit relative (in words) 
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A.6 Line Number Table 

The object file contains a table of line number entries that are useful for sym¬ 
bolic debugging. When the C compiler produces several lines of assembly 
language code, it creates a line number entry that maps these lines back to the 
original line of C source code that generated them. Each single line number 
entry contains 6 bytes of information. Table A-8 shows the format of a line 
entry. 


Table A-8. Line Number Entry Format 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

This entry may have one of two values: 

1) If it is the first entry in a block of line 
number entries, it points to a symbol 
entry in the symbol table 

2) If it is not the first entry in a block, it is 
the physical address of the line indi¬ 
cated by bytes 4-5 

4-5 

Unsigned short integer 

This entry may have one of two values: 

1) If this field is 0, then this is the first line 
of a function entry 

2) If this field is not 0, then this is the line 
number of a line of C source code 


Figure A-4 shows how line number entries are grouped into blocks. 


Symbol Index 

0 

physical address 

line number 

physical address 

line number 



Symbol Index 

0 

physical address 

line number 

physical address 

line number 


Figure A-4. Line Number Blocks 

Each entry is divided into halves (as shown in Table A-8): 

• For the first line of a function, 

- Bytes 0-3 point to the name of a symbol or a function in the 
symbol table. 

Bytes 4-5 contain a 0, which indicates the beginning of a block. 

• For the remaining lines in a function, 

- Bytes 0-3 show the physical address (the number of words created 
by a line of C source). 

- Bytes 4-5 show the address of the original C source, relative to its 
appearance in the C source program. 

The line entry table can contain many of these blocks. 
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Figure A-5 illustrates an example of line number entries for a function named 
xyz. As shown, the function name is entered as a symbol in the symbol table. 
The first portion on xyz's block of line number entries points to the function 
name in the symbol table. Assume that the original function in the C source 
contained three lines of code. The first line of code produces 4 words, the 
second line produces 3 words, and the third line produces 10 words. Figure 
A-5 shows what the line number entries would look like for this example. 


File Header 


Optional File Header 


Section 1 Header 


Section n Header 


Section 1 
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Section 1 

Retocation information 


Section n 
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Section n 
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Symbol Table 


String Table 
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Raw Data 
(executable code 
and initialized data) 


Relocation Information 


Line Number 
Entries 


Figure A-5. Line Number Entries Example 


(Note that the symbol table entry for xyz has a field that points back to the 
beginning of the line number block.) 

Since line numbers are not often needed, the linker provides an option (-s) 
that strips line number information from the object file; this provides a more 
compact object module. 
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A.7 Symbol Table 

The order of symbols in the symbol table is very important; they appear in the 
sequence shown in Figure A-6. 


File Name 1 

Function 1 

Local symbols 
for Function 1 

Function 2 

Local symbols 
for Function 2 


File Name 2 

Function 1 

Local symbols 
for Function 1 


Static variables 


Defined global symbols 

Undefined global symbols 


Figure A-6. Symbol Table Contents 


Static variables refer to symbols defined in C that have storage class static 
outside any function. If you have several modules that use symbols with the 
same name, making them static confines the scope of each symbol to the 
module that defines it (this eliminates multiple-definition conflicts). 

The entry for each symbol in the symbol table contains the symbol's: 

• Name (or a pointer into the string table) 

• Type 

• Value 

• Section it was defined in 

• Storage class 

• Basic type (integer, character, etc.) 

• Derived type (array, structure, etc.) 

• Dimensions 

• Line number of the source code that defined the symbol 
Section names are also defined in the symbol table. 
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All symbol entries, regardless of the symbol's class and type, have the same 
format in the symbol table. Each symbol table entry contains the 18 bytes of 
information listed in Table A-9. Each symbol may also have an 18-byte aux¬ 
iliary entry; the special symbols listed in Table A-10 always have auxiliary en¬ 
tries. Some symbols may not have all the characteristics listed above; if a 
particular field is not set, it is set to null. 

Table A-9. Symbol Table Entry Contents 


Byte 

Number 

Type 

Description 

0-7 

Character 

This field contains one of the following: 

1) An 8-character symbol name, padded 
with nulls 

2) A pointer into the string table if the 
symbol name is longer than 8 charac¬ 
ters 

8-11 

Long integer 

Symbol value; storage class dependent 

12-13 

Short integer 

Section number of the symbol 

14-15 

Unsigned short integer 

Basic and derived type specification 

16 

Character 

Storage class of the symbol 

17 

Character 

Number of auxiliary entries (always 0 or 1) 


A.7.1 Special Symbols 

The symbol table contains some special symbols that are generated by the 
compiler, assembler, and linker. Each special symbol contains ordinary symbol 
table information as well as an auxiliary entry. Table A-10 lists these symbols. 

Table A-10. Special Symbols in the Symbol Table 


Symbol 

Description 

.file 

File name 

.text 

Address of the .text section 

.data 

Address of the .data section 

.bss 

Address of the .bss section 

.bb 

Address of the beginning of a block 

.eb 

Address of the end of a block 

.bf 

Address of the beginning of a function 

.ef 

Address of the end of a function 

.target 

Pointer to a structure or union that is returned by a function 

,A?fake 

Dummy tag name for a structure, union, or enumeration 

.eos 

End of a structure, union, or enumeration 

—etext, etext 

Next available address after the end of the .text output section 

—edata, edata 

Next available address after the end of the .data output section 

—end, end 

Next available address after the end of the .bss output section 
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Several of these symbols appear in pairs: 

• .bb/.eb indicate the beginning and ending of a block. 

• .bf/.ef indicate the beginning and ending of a function. 

• ./?fake/.eos name and define the limits of structures, unions, and enu¬ 
merations that were not named. The .eos symbol is also paired with 
named structures, unions, and enumerations. 

When a structure, union, or enumeration has no tag name, the compiler as¬ 
signs it a name so that it can be entered into the symbol table. These names 
are of the form .rtfake, where n is an integer. The compiler begins numbering 
these symbol names at 0. 

A.7.1.1 Symbols and Blocks 

In C, a block is a compound statement that begins and ends with braces. A 
block always contains symbols. The symbol definitions for any particular 
block are grouped together in the symbol table, and are delineated by the 
.bb/.eb special symbols. Note that blocks can be nested in C, and their symbol 
table entries can also be nested correspondingly. Figure A-7 shows how 
block symbols are grouped in the symbol table. 


Block 1: 


Block 2: 


Figure A-7. Symbols for Blocks 


Symbol Table 

.bb 

Symbols for 
block 1 

_£b_ 

_ .bb _ 

Symbols for 
block 2 

.eb 


A.7.1.2 Symbols and Functions 

The symbol definitions for a function appear in the symbol table as a group, 
delineated by .bf/.ef special symbols. The symbol table entry for name of the 
function precedes the .bf special symbol. Figure A-8 shows the format of 
symbol table entries for a function. 


Function Name 
.bf 

Symbols for 
the function 

.ef 


Figure A-8. Symbols for Functions 
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If a function returns a structure or union, then a symbol table entry for the 
special symbol .target will appear between the entries for the function name 
and the .bf special symbol. 

A.7.2 Symbol Names 

The first 8 bytes of a symbol table entry (bytes 0-7) indicate a symbol's name: 

• If the symbol name is 8 characters or less, than this field has type char¬ 
acter. the name is padded with nulls (if necessary) and stored in bytes 
0-7. 

• If the symbol name is greater than 8 characters, then this field is treated 
as two long integers. The entire symbol name is stored in the string ta¬ 
ble. Bytes 0-3 contain 0, and bytes 4-7 are an offset into the string table. 

A.7.3 String Table 

Symbol names that are longer than eight characters are stored in the string 
table. The field in the symbol table entry that would normally contain the 
symbol's name instead contains a pointer to the symbol's name in the string 
table. Names are stored contiguously in the string table, delimited by a null 
byte. The first four bytes of the string table contain the size of the string table 
in bytes; thus, offsets into the string table are greater than or equal to four. 

Figure A-9 shows an example of a string table that contains two symbol 
names, Rotation-Coordinate and Shade—Pattern. The index in the 
string table is 4 for Rotation—Coordinate and 24 for Shade—Pattern. 


38 

'R' 

'o' 

Y 

'a' 

't' 

'V 

'o' 

'n' 


'C' 

'o' 

'o' 

'r' 

'd' 

'i' 

'n' 

'a' 

Y 

'e' 

'\0' 

'S' 

'h' 

'a' 

'd' 

'e' 


'P' 

'a' 

't' 

Y 

'e' 

'r' 

'n' 

'\0' 



Figure A-9. Sample String Table 
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A.7.4 Storage Classes 

Byte 16 of the symbol table entry indicates the storage class of the symbol. 
Storage classes refer to the method in which the C compiler accesses a sym¬ 
bol. Table A-11 lists valid storage classes. 

Table A-11. Symbol Storage Classes 


Mnemonic 

Value 

Storage Class 

Mnemonic 

Value 

Storage Class 

C—NULL 

0 

No storage class 

C-UNTAG 

12 

Union tag 

C-AUTO 

1 

Automatic variable 

C-TPDEF 

13 

Type definition 

C-EXT 

2 

External symbol 

C-USTATIC 

14 

Uninitialized static 

C-STAT 

3 

Static 

C-ENTAG 

15 

Enumeration tag 

C-REG 

H 

Register variable 

C-MOE 

16 

Member of an enumer¬ 
ation 

C-EXTDEF 

5 

External definition 

C—REGPARM 

17 

Register parameter 

C-LABEL 

6 

Label 

C—FIELD 

18 

Bit field 

C-ULABEL 

■ 

Undefined label 

C-BLOCK 

100 

Beginning or end of a 
block; used only for the 
.bb and .eb special sym¬ 
bols 

C-MOS 

8 

Member of a structure 

C—FCN 

101 

Beginning or end of a 
function; used only for 
the ,bf and .ef special 
symbols 

C-ARG 

9 

Function argument 

C-EOS 

102 

End of structure; used 
only for the .eos special 
symbol 

C-STRTAG 

10 

Structure tag 

C-FILE 

103 

Filename; used only for 
the .file special symbol 

C-MOU 

11 

Member of a union 

C—LINE 

104 

Used only by utility pro¬ 
grams 


Some special symbols are restricted to certain storage classes. Table A-12 lists 
these symbols and their storage classes. 

Table A-12. Special Symbols and Their Storage Classes 


Special 

Symbol 

Restricted to 
this 

Storage Class 

.file 

C-FILE 

.bb 

C-BLOCK 

.eb 

C-BLOCK 

.bf 

C—FCN 

.ef 

C—FCN 

.eos 

C-EOS 

.text 

C-STAT 

.data 

C-STAT 

.bss 

C-STAT 
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A.7.5 Symbol Values 

Bytes 8-11 of a symbol table entry indicate a symbol's value. A symbol's value 
depends on the symbol's storage class; Table A-13 summarizes the storage 
classes and related values. 

Table A-13. Symbol Values and Storage Classes 


Storage Class 

Value Description 

C-AUTO 

Stack offset in bits 

C-EXT 

Relocatable address 

C-STAT 

Relocatable address 

C-REG 

Register number 

C-LABEL 

Relocatable address 

C-MOS 

Offset in bits 

C-ARG 

Stack offset in bits 

C-STRTAG 

0 

C-MOU 

Offset in bits 

C-UNTAG 

0 

C-TPDEF 

0 

C-ENTAG 

0 

C-MOE 

Enumeration value 

C—REGPARM 

Register number 

C—FIELD 

Bit displacement 

C-BLOCK 

Relocatable address 

C-FCN 

Relocatable address 

C-FILE 

0 


If a symbol's storage class is C—FILE, then the symbol's value is a pointer to 
the next .file symbol. Thus, the .file symbols form a one-way linked list in the 
symbol table. When there are no more .file symbols, the final .file symbol 
points back to the first .file symbol in the symbol table. 

The value of a relocatable symbol is its virtual address. When the linker relo¬ 
cates a section, the value of a relocatable symbol changes accordingly. 
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A.7.6 Section Number 

Bytes 12-13 of a symbol table entry contain a number that indicates which 
section the symbol was defined in. Table A-14 lists these numbers and the 
sections they indicate. 

Table A-14. Section Numbers 


Mnemonic 

Section 

Number 

Description 

N-DEBUG 

-2 

Special symbolic debugging symbol 

N-ABS 

-1 

Absolute symbol 

N-UNDEF 

0 

Undefined external symbol 

N-SCNUM 

1 

.text section 

N-SCNUM 

2 

.data section 

N-SCNUM 

3 

.bss section 

N-SCNUM 

4-77,777 

Section number of a named section, in 
the order in which the named sections 
are encountered 


Note that if there were no .text, .data, or .bss sections, the numbering of 
named sections would begin with 1. 

If a symbol has a section number of 0, -1, or -2, then it is not defined in a 
section. A section number of -2 indicates a symbolic debugging symbol, 
which includes structure, union, and enumeration tag names, type definitions, 
and the filename. A section number of -1 indicates that the symbol has a va¬ 
lue but is not relocatable. A section number of 0 indicates a relocatable ex¬ 
ternal symbol that is not defined in the current file. 

A.7.7 Type Entry 

Bytes 14-15 of the symbol table entry define the symbol's type. Each symbol 
symbol has: 

• One basic type 

• One to six derived types 

The format for this 16-bit type entry is: 


Derived 

Derived 

Derived 

Derived 

Derived 

Derived 

Basic 

Type 

Type 

Type 

Type 

Type 

Type 


6 

5 

4 

3 

2 

1 

Type 


Size (in bits): 2 2 2 2 2 2 4 
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Bits 0-3 of the type field indicate the basic type. Table A-15 lists valid basic 
types. 

Table A-15. Basic Types 


Mnemonic 

Value 

Type 

T-NULL 

0 

Type not assigned 

T-CHAR 

2 

Character 

T-SHORT 

3 

Short integer 

T-INT 

4 

Integer 

T-LONG 

5 

Long integer 

T-FLOAT 

6 

Floating point 

T-DOUBLE 

7 

Double word 

T-STRUCT 

8 

Structure 

T—UNION 

9 

Union 

T-ENUM 

10 

Enumeration 

T-MOE 

11 

Member of an enumeration 

T-UCHAR 

12 

Unsigned character 

T-USHORT 

13 

Unsigned short integer 

T-UINT 

14 

Unsigned integer 

T-ULONG 

15 

Unsigned long integer 


Bits 4-15 of the type field are arranged as six 2-bit fields which can indicate 
1 to 6 derived types. Table A-16 lists the possible derived types. 

Table A-16. Derived Types 


Mnemonic 

Value 

Type 

DT-NON 

0 

No derived type 

DT-PTR 

1 

Pointer 

DT-FCN 

2 

Function 

DT-ARY 

3 

Array 


An example of a symbol with several derived types would be a symbol with a 
type entry of 0000000011010011 2 - This entry indicates that the symbol is 
an array of pointers to short integers. 
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A.7.8 Auxiliary Entries 

Each symbol table may have a one or no auxiliary entry. An auxiliary table 
entry contains the same number of bytes as a symbol table entry (18), but the 
format of an auxiliary entry depends on its type and storage class. Table A-17 
summarizes these relationships. 


Table A-17. Auxiliary Symbol Table Entries Format 



Storage 

Class 

Type Entry 

Auxiliary 

Entry Format 

Name 

Derived 
Type 1 

Basic 

Type 

.file 

C-FILE 

DT-NON 

T-NULL 

Filename (see Table A-18) 

.text, .data, .bss 

C-STAT 

DT-NON 

T-NULL 

Section (see Table A-19) 

tagname 

C-STRTAG 

C-UNTAG 

C-ENTAG 

DT-NON 

T-NULL 

Tag name (see Table A-20) 

.eos 

C-EOS 

DT-NON 

T-NULL 

End of structure (see Table A-21) 

fcname 

C-EXT 

C-STAT 

DT-FCN 

(See note 1) 

Function (see Table A-22) 

arrname 

(See note 2) 

DT-ARY 

(See note 1) 

Array (see Table A-23) 

.bb, .eb 

C-BLOCK 

DT-NON 

T-NULL 

Beginning and end of a block 
(see Table A-24 and Table A-25) 

.bf, .ef 

C-FCN 

DT-NON 

T-NULL 

Beginning and end of a function 
(see Table A-24 and Table A-25) 

Name related to a 
structure, union 
or enumeration 

(See note 2) 

DT-PTR 

DT-ARR 

DT-NON 

T-STRUCT 
T—UNION 
T-ENUM 

Name related to a structure, union, 
or enumeration (see Table A-26) 


Notes: 1) Any except T— MOE. 

2) C-AUTO, C-STAT, C-MOS, C-MOU, C-TPDEF. 


In Table A-17, tagname refers to any symbol name (including the special 
symbol ./7fake). Fcname and arrname refer to any symbol name. 

Any symbol that satisfies more than one condition in Table A-17 should have 
a uninon format in its auxiliary entry. Any symbol that does not satisfy any 
of these conditions should not have an auxiliary entry. 

A.7.8.1 Filenames 


Each of the auxiliary table entries for a file name contains a 14-character file 
name in bytes 0-13. Bytes 14-17 are unused. 

Table A-18. Filename Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-13 

Character 

File name 

14-17 

- 

Unused 
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A.7.8.2 Sections 

Table A-19 shows the format of the auxiliary table entries for sections. 

Table A-19. Section Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Section length 

4-6 

Unsigned short integer 

Number of relocation entries 

7-8 

Unsigned short integer 

Number of line number entries 

9-17 

- 

Not used (zero filled) 


A.7.8.3 Tag Names 

Table A-20 illustrates the format of auxiliary table entries for tag names. 

Table A-20. Tag Name Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-5 

- 

Unused (zero filled) 

6-7 

Unsigned short integer 

Size of structure, union, or enumeration 

8-11 

- 

Unused (zero filled) 

12-15 

Long integer 

Index of next entry beyond this structure, 
union, or enumeration 

16-17 

- 

Unused (zero filled) 


A.7.8.4 End of Structure 


Table A-21 illustrates the format of auxiliary table entries for ends of struc¬ 
tures. 

Table A-21. End of Structure Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-5 

- 

Unused (zero filled) 

6-7 

Unsigned short integer 

Size of structure, union, or enumeration 

8-17 

- 

Unused (zero filled) 
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A.7.8.5 Functions 

Table A-22 illustrates the format of auxiliary table entries for functions. 

Table A-22. Function Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-7 

Long integer 

Size of function (in bits) 

8-11 

Long integer 

File pointer to line number 

12-15 

Long integer 

Index of next entry beyond this function 

16-17 

- 

Unused (zero filled) 


A.7.8.6 Arrays 

Table A-23 illustrates the format of auxiliary table entries for arrays. 

Table A-23. Array Format for Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-5 

Unsigned short integer 

Line number declaration 

6-7 

Unsigned short integer 

Size of array 

8-9 

Unsigned short integer 

First dimension 

10-11 

Unsigned short integer 

Second dimension 

12-13 

Unsigned short integer 

Third dimension 

14-15 

Unsigned short integer 

Fourth dimension 

16-17 

- 

Unused (zero filled) 


A.7.8.7 End of Blocks and Functions 

Table A-24 illustrates the format of auxiliary table entries for the ends of blocks 
and functions. 

Table A-24. End of Blocks and Functions Format for Auxiliary Table 

Entries 


Byte 

Number 

Type 

Description 

0-3 

" 

Unused (zero filled) 

4-5 

Unsigned short integer 

C source line number 

6-17 

- 

Unused (zero filled) 
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A.7.8.8 Beginning of Blocks and Functions 

Table A-25 illustrates the format of auxiliary table entries for the beginnings 
of blocks and functions. 


Table A-25. Beginning of Blocks and Functions Format for 
Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

- 

Unused (zero filled) 

4-5 

Unsigned short integer 

C source line number 

6-11 

- 

Unused (zero filled) 

12-15 

Long integer 

Index of next entry past this block 

16-17 

- 

Unused (zero filled) 


A.7.8.9 Names Related to Structures, Unions, and Enumerations 

Table A-26 illustrates the format of auxiliary table entries for the names of 
structures, unions, and enumerations. 

Table A-26. Structure, Union, and Enumeration Names Format for 
Auxiliary Table Entries 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-5 

- 

Unused (zero filled) 

6-7 

Unsigned short integer 

Size of the structure, union, or enumeration 

8-17 

- 

Unused (zero filled) 

16-17 

- 

Unused (zero filled) 
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Appendix B 

Symbolic Debugging Directives 


i 


The TMS34010 assembler supports several directives that the TMS34010 C 
compiler uses for symbolic debugging: 

• The .sym directive defines a global variable, a local variable, or a func¬ 
tion. Several parameters allow you to associate various debugging in¬ 
formation with the symbol or function. 

• The .stag, .etag, and .utag directives define structures, enumerations, 
and unions, respectively. 

• The .member directive specifies a member of a structure, enumeration, 
or union. 

• The .eos directive ends a structure, enumeration, or union definition. 

• The .func and .endfunc directives specify the beginning and ending 
lines of a C function. 

• The .func and .endfunc directives specify the bounds of C blocks. 

• The .file directive defines a symbol in the symbol table that identifies the 
current source file name. 

• The .line directive identifies the line number of a C source statement. 

These symbolic debugging directives are not usually listed in the assembly 
language file that the compiler creates. If you want them to be listed, invoke 
the code generator with the -o option, as shown below: 

gspcg -o input file 

This appendix contains an alphabetical directory of the symbolic debugging 
directives. Each directive contains an example of C source and the resulting 
assembly language code. 
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.block/.endblock 


Define a Block 


Syntax 


Description 


Example 


.block beginning line number 
.endblock ending line number 

The .block and .endblock directives specify the beginning and end of a C 
block. The line numbers are optional; they specify the location in the source 
file where the block is defined. 

Note that block definitions can be nested. The assembler will detect im¬ 
proper block nesting. 

Here is an example of C source that defines a block, and the resulting as¬ 
sembly language code. 

C source: 


{ 

int a,b; 
a = b; 

} 


/* Beginning of a block */ 
/* End of a block */ 


Resulting assembly language code: 

.func 2 

.sym _a,0,4,1,32 
.sym _b,32,4,1,32 
.line 3 
.endfunc 5 




Supply a File Identifier 


.file 


Syntax 

Description 


Example 


.file " filename " 

The .file directive allows a debugger to map locations in memory back to 
lines in a C source file. Filename is the name of the file that contains the 
orginal C source program. The first 14 characters of the filename are sig¬ 
nificant; any pathname information is stripped away. 

You can also use the .file directive in assembly code to provide a name in 
the file and improve program readability. 

Here's an example of the .file directive. The file named text.c contained the 
C source that produced this directive. 

.file "text.c" 
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.func/.endfunc 


Define a Function 


Syntax .func beginning line number 

.endfunc ending line number 

Description The .func and .endfunc directives specify the beginning and end of a C 
function. The line numbers are optional; they specify the location in the 
source file where the function is defined. 

Note that function definitions cannot be nested. 

Example Here is an example of C source that defines a function, and the resulting 

assembly language code. 

C source: 

power(x, n) /* Beginning of a function */ 

int x,n; 

{ 

int i, p; 
p = I? 

for (i = 1; i <= n; ++i) 
p = p * x; 

return p; /* End of function */ 

} 
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Define a Function 


func/.endfunc 


Resulting assembly language code: 

0056 .sym —power,—power,36,2,0 

0057 .globl —power 

0058 

0059 .func 8 

0060 

****************************************************** 
0061 * FUNCTION DEF : -power 

0062 

****************************************************** 


0063 

000002E0 


—power: 


0064 

000002E0 

098F 

MMTM 

SP,A5,A7,A12,FP 


000002F0 

050C 



0065 

00000300 

4DCD 

MOVE 

STK,FP 

0066 

00000310 

OBOE 

ADDI 

64,STK 


00000320 

0040 



0067 



. sym 

_x,-32,4,9,32 

0068 



. sym 

_n,-64,4,9,32 

0069 



. sym 

_i,0,4,1,32 

0070 



. sym 

_p,32,4,1,32 

0071 

00000330 


. line 

3 

0072 

00000330 

182C 

MOVK 

1, A12 

0073 

00000340 

B38D 

MOVE 

A12,*FP(32),1 


00000350 

0020 



0074 

00000360 


. line 

4 

0075 

00000360 

838D 

MOVE 

A12,*FP,1 

0076 

00000370 


L6: 


0077 

00000370 

87A7 

MOVE 

*FP,A7,1 

0078 

00000380 

B7A5 

MOVE 

*FP(-64),A5,1 


00000390 

FFC0 



0079 

000003A0 

48A7 

CMP 

A5,A7 

008,0 

000003B0 

C70B 

JRGT 

L5 

0081 

000003C0 


. line 

5 

0082 

000003C0 

B7A7 

MOVE 

*FP(32),A7,1 


000003D0 

0020 



0083 

000003E0 

B7A5 

MOVE 

*FP(-32),A5,1 


000003F0 

FFE0 



0084 

00000400 

5CA7 

MPYS 

A5,A7 

0085 

00000410 

B2ED 

MOVE 

A7 ,*FP(32) ,1 


00000420 

0020 



0086 

00000430 

87A7 

MOVE 

*FP,A7,1 

0087 

00000440 

1027 

ADDK 

1, A7 

0088 

00000450 

82ED 

MOVE 

A7 ,*FP,1 

0089 

00000460 

C0F0 

JRUC 

L6 

0090 

00000470 


L5 : 


0091 

00000470 


. line 

6 

0092 

00000470 

B7A8 

MOVE 

*FP(32),A8,1 


00000480 

0020 



0093 

00000490 


EPIO-2: 


0094 

00000490 

B7EE 

MOVE 

*SP(160),STK,1 


000004A0 

00A0 



0095 

000004B0 

09AF 

MMFM 

SP,A5,A7,A12,FP 


000004C0 

30A0 



0096 

000004D0 

0962 

RETS 

2 


0097 

0098 .endfunc 15 
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.line 


Create a Line Number Entry 


Syntax 

Description 


Example 


.line line number [, address] 

The .line directive creates a line number entry in the object file. Line number 
entries are used in symbolic debugging to associate addresses in the object 
code with the lines in the source code that generated them. 

The .line directive has two operands: 

• Line number indicates the line of the C source that generated a por¬ 
tion of code. Line numbers are relative to the beginning of the current 
function. This is a required parameter. 

• Address is an expression which is the address associated with the line 
number. This is an optional parameter; if you don't specify an address, 
the assembler will use the current SPC value. 


The .line directive is followed by the assembly language source statements 
that are generated by the indicated line of C source. For example, assume 
that the lines of C source below are line 4 and 5 in the original C source; 
lines 5 and 6 produce the assembly language source statements that are 
shown below. 

C source: 

P = 1; 

for (i = 1; i <= n; ++i) 

P = P * x; 


Resulting assembly language code: 


0074 

00000360 



. line 

4 

0075 

00000360 

838D 


MOVE 

A12,*FP,1 

0076 

00000370 


L6: 



0077 

00000370 

87A7 


MOVE 

*FP,A7,1 

0078 

00000380 

B7A5 


MOVE 

*FP(-64),A5,1 


00000390 

FFC0 




0079 

000003A0 

48A7 


CMP 

A5 , A7 

0080 

000003B0 

C70B 


JRGT 

L5 

0081 

000003C0 



. line 

5 

0082 

000003C0 

B7A7 


MOVE 

*FP(32),A7,1 


000003DO 

0020 




0083 

000003E0 

B7A5 


MOVE 

*FP(-32),A5,1 


000003F0 

FFE0 




0084 

00000400 

5CA7 


MPYS 

A5,A7 

0085 

00000410 

B2ED 


MOVE 

A7,*FP(32),1 


00000420 

0020 




0086 

00000430 

87A7 


MOVE 

*FP,A7,1 

0087 

00000440 

1027 


ADDK 

1, A7 

0088 

00000450 

82ED 


MOVE 

A7 ,*FP,1 

0089 

00000460 

C0F0 


JRUC 

L6 

0090 

00000470 


L5 : 



0091 

00000470 



. line 

6 

0092 

00000470 

B7A8 


MOVE 

*FP(32),A8,1 


00000480 

0020 







Define a Member 


.member 


Syntax .member name, value [, type, storage class, size, tag, dims] 

Description The .member directive defines a member of a structure, union, or enumer¬ 
ation. It is only valid when it appears in a structure, union, or enumeration 
definition. 

• Name is the name of the member that is put in the symbol table. The 
first 32 characters of the name are significant. 

• Value is the value associated with the member. Any legal expression 
(absolute or relocatable) is acceptable. 

• Type is the C type of the member. Appendix A contains more infor¬ 
mation about C types. 

• Storage class is the C storage class of the member. Appendix A con¬ 
tains more information about C storage classes. 

• Size is the number of bits of memory required to contain this member. 

• Tag is the name of the type (if any) or structure of which this member 
is a type. This name must have been previously declared by a .stag, 
.etag, or .utag directive. 

• Dims may be one to four expressions separated by commas. This al¬ 
lows up to four dimensions to be specified for the member. 

The order of parameters is significant. Name and value are required pa¬ 
rameters. All other parameters may be omitted or empty (adjacent commas 
indicate an empty entry). This allows you to skip a parameter and specify 
a parameter that occurs later in the list. Operands that are omitted or empty 
assume a null value. 

Example Here is an example of a C structure definition and the corresponding as¬ 

sembly language statements: 

C source: 

struct doc 
{ 

char title; 
char group; 
int job-number; 

} doc—info; 

Resulting assembly language code: 

.stag —doc,48 

.member —title,0,2,8,8 
.member —group,8,2,8,8 
.member —job—number,16,4,8,32 

. eos 
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.stag/.etag/. utag/.eos 


Define a Structure 


Syntax .stag name [, size] 

member definitions 

.eos 

.etag name [, size] 
member definitions 

.eos 

.utag name [, size] 
member definitions 

.eos 

Description The .stag directive begins a structure definition. The .etag directive begins 
an enumeration definition. The .utag directive begins a union definition. 
The .eos directive ends a structure, enumeration, or union definition. 

• Name is the name of the structure, enumeration, or union. The first 
32 characters of the name are significant. This is a required parameter. 

• Size is the number of bits the structure, enumeration, or union occu¬ 
pies in memory. This is an optional parameter; if omitted, the size is 
unspecified. 

The .stag, .etag, or.utag directive should be followed by a number of 
.member directives, which define members in the structure. The .member 
directive is the only directive that can appear inside a structure, enumer¬ 
ation, or union definition. 

The assembler does not allow nested structures, enumerations, or unions. 
The C compiler "unwinds" nested structures by defining them separately 
and then referencing them from the structure they are referenced in. 

Example 1 Here is an example of a structure definition. 

C source: 

struct doc 
{ 

char title; 
char group; 
int job-number; 

} doc—info; 

Resulting assembly language code: 

.stag —doc,48 
.member _title,0,2,8,8 
.member _group,8,2,8,8 
.member —job—number,16,4,8,32 
. eos 
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Define a Structure 


.stag/.etag/.utag/.eos 


Example 2 


Example 3 


Here is an example of a union definition. 

C source: 

union u—tag { 

int vail; 
float val2; 
char vale; 

} valu; 

Resulting assembly language code: 

.utag —u_tag,32 

.member _vall,0,4,11, 32 
.member —val2,0,6,11, 32 
.member _vale,0,2,11,8 
. eos 


Here is an example of an enumeration definition. 

C Source: 

{ 

enum o—ty { reg—1, reg— 2 , result } optypes; 

} 

Resulting assembly language code: 

.etag —o_ty,2 

.member —reg—1,0,11,16, 2 
.member —reg_2,1,11,16,2 
.member —result, 2 ,li,16, 2 
. eos 
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.sym 


Define a Symbol 


Syntax 

Description 


Example 


.sym name, value [, type, storage class, size, tag , dims] 

The .sym directive specifies symbolic debug information about a global 
variable, local variable, or a function. 

• Name is the name of the variable that is put in the object symbol table. 
The first 32 characters of the name are significant. 

• Value is the value associated with the variable. Any legal expression 
(absolute or relocatable) is acceptable. 

• Type is the C type of the variable. Appendix A contains more infor¬ 
mation about C types. 

• Storage class is the C storage class of the variable. Appendix A con¬ 
tains more information about C storage classes. 

• Size is the number of words of memory required to contain this vari¬ 
able. 

• Tag is the name of the type (if any) or structure of which this variable 
is a type. This name must have been previously declared by a .stag, 
.etag, or .utag directive. 

• Dims may be up to four expressions separated by commas. This al¬ 
lows up to four dimensions to be specified for the variable. 

The order of parameters is significant. Name and value are required pa¬ 
rameters. All other parameters may be omitted or empty (adjacent commas 
indicate an empty entry). This allows you to skip a parameter and specify 
a parameter that occurs later in the list. Operands that are omitted or empty 
assume a null value. 

These lines of C source produce the .sym directives shown below: 

C source: 

struct s { int member1, member2; } str; 
int ext; 

int array[5] [10] ; 
long *ptr; 
int strcmp(); 

main(argl,arg2) 
int argl; 
char *arg2; 

{ 

register AO; 

} 
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Define a Symbol 


.sym 


Resulting assembly language code: 

.sym ~str,—str,8,2,64,_s 

.sym —ext,_ext,4,2,32 

.sym —array,—array,244,2,1600,,5,10 

.sym —ptr,—ptr,21,2,32 

.sym —main,—main,36,2,0 

.sym _argl,-32,4,9,32 

.sym _arg2,-64,18,9,32 

.sym _A0,9,4,4,32 
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Appendix C 

Assembler Error Messages 


The assembler issues several types of error messages: 

• Fatal, 

• Nonfatal, and 

• Macro errors. 

When the assembler completes it second pass, it reports on any errors that it 
encountered during the assembly. It also prints these errors in the listing file 
(if one is created); an error is printed following the source line that incurred 
it. 

This section discusses the three types of assembler error messages; they are 
listed in alphabetical order. Most errors are fatal errors; if an error is not fatal 
or if it is a macro error, this is noted in the list. 

absolute value required: A relocatable symbol was used where an absolute 
symbol was required. 

a component of the expression is invalid: Check the format of the con¬ 
stants in the expression. 

an identifier in the expression is invalid 

bad field width: The minimum field width is 0, the maximum field width is 
32. 

bad macro definition (macro error) 

blank missing: One or more blanks must separate the fields of a source 
statement. 

cannot open library: A library name specified with the .mlib directive does 
not exist or is already being used. 

character constant is wider than 4 characters The maximum size of a 
character constant is 4 characters. 

close ( ] ) missing: Mismatched brackets. 

close ( ) ) missing: Mismatched parentheses. 

close quote missing: Mismatched quotes. 

conflicts with previous section definition 

comma missing: The assembler expected a comma but did not find one. 
This usually means that more operands were expected. 
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copy file open error: A file specified with the .copy or .include directive 
does not exist or is already being used. 

divide by zero: An expression or well-defined expression contains invalid 
division. 

duplicate definition: The symbol appears as an operand of a REF state¬ 
ments and is also used as a label, or, the symbol appears more than once in 
the label field. 

$END statement missing in macro (macro error): Within the macro li¬ 
brary, an end of file was encountered before an $END statement. 

ELSE needs corresponding IF (macro error): The ELSE statement is valid 
only within a conditional block that is started with an IF statement. 

expression not terminated properly 

expression out of bounds 

filename missing: This specified filename cannot be found. 

illegal operation in expression 

illegal structure definition 

illegal structure, union, or enumeration tag 

$IF level exceeded (macro error): Conditional blocks can only be nested to 
a maximum of 44 levels within a macro definition. 

include/copy files not allowed in macros (macro error): You cannot use 
the .copy or .include directive within a macro. 

incompatible addressing modes: An invalid combination of addressing 
modes has been used in an instruction. 

incorrect macro definition (macro error): Within the macro library, a ma¬ 
cro was not found or a macro name was not given for a macro call. 

indirect (*) missing 

invalid binary constant: The only valid binary integers are 0 and 1; the 
constant must be suffixed with b or B. 

invalid branch displacement 

invalid decimal constant: The only valid decimal integers are 0-9. 

invalid expression: This may indicate invalid use of a relocatable symbol in 
an expression. 

invalid floating point constant 
invalid IF/LOOP nesting (macro error) 
invalid IF structure (macro error) 
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invalid hexadecimal constant: The only valid hexadecimal digits are the 
integers 0-9 and the letters A-F. The constant must be suffixed with h or H 
and it must begin with an integer. 

invalid macro library pathname (macro error): The macro library name 
that was specified with an .mlib directive is invalid. 

invalid macro qualifier (macro error): The only valid macro qualifiers are 
S, V, L, A, SS, SV, SL, and SA. 

invalid macro verb (macro error) 

invalid octal constant: Valid octal digits include 0-7; the constant must 
be suffixed with q or Q. 

invalid opcode: The command field of the source statement has an entry that 
is not defined as an instruction, directive, or macro. 

invalid option: An option specified with the .option directive is not legal. 

invalid register value 
invalid symbol 

label required: The flagged directive must have a label. 

library not in archive format: A file specified with the .mlib directive is 
not an archive library. 

LOOP nesting level exceeded (macro error) 

long macro variable qualifier (macro error) 

macro line too long (macro error) 

macro nesting level exceeded (macro error) 

macro variable component specified is illegal (macro error) 

maximum number of copy files exceeded 

open quote missing: Mismatched quotes. 

operand missing 

overflow in floating point constant 

pass1/pass2 operand conflict 

positive value required 

register required 

registers in opposite files 

string required 

symbol required 

syntax error 
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symbol used in both ref and def 
target address not word aligned 
too many array dimensions 
too many macro variables (macro error) 
unbalanced symbol table entries 

undefined symbol: An undefined symbol was used where a well-defined 
expression was expected. 

unexpected endif encountered (macro error) 
underflow in floating point constant 
value truncated 

variable already defined (macro error) 

warning - byte value truncated: The specified value cannot be expresses 
in 8 bits. 

warning - line truncated: The maximum line length is 200 characters. 

warning - null string defined 

warning - register converted to immediate 

warning - SP will be corrupted 

warning - string length exceeds maximum limit 

warning - symbol truncated: Symbol names are significant to 32 charac¬ 
ters. 

warning - trailing operand(s) 

warning - unexpected .end found in macro 

warning - value out of range 

warning - value truncated 
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Appendix D 

Linker Error Messages 


The linker issues several types of error messages: 

• Syntax and command errors 

• Allocation errors 

• I/O errors 

This section discusses the three types of errors; they are listed alphabetically 
within each category. The symbol "(...)" is used in these listings to represent 
the name of an object that the linker is attempting to interact with when an 
error occurs. 

• Syntax/Command Errors 

These errors are caused by incorrect use of linker directives, misuse of 
an input expression, invalid options. Check the syntax of all expressions, 
check the input directives for accuracy. Review the various options you 
are using and check for conflicts. 

absolute symbol (...) being redefined: An absolute symbol may 
not be redefined. 

adding name (...) to multiple output sections: The input section 
is mentioned twice in the SECTION directive. 

ALIGN illegal in this context: Alignment of a symbol may only be 
performed within a SECTIONS directive. 

attempt to decrement 

bad attribute value in MEMORY directive: (...): An attribute must 

be R, W, X, or I. 

bad flag value in SECTIONS directive, option (...) 

bad fill value: The fill value must be a 4-byte constant. 

binding excludes alignment: The section will be bound at the spe¬ 
cified address regardless of the alignment of that address. 

both -r and -s flags are set; -s flag turned off: Since the -s option 
strips the relocation information and -r requests a relocatable object file, 
these options are in conflict with each other. 

-c requires fill value of 0 in .cinit: The value parameter has been 
overridden. 

-f flag does not specify a fill value 
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cannot align a section within GROUP - (...) not aligned 
cannot bind a section within a GROUP 

cannot specify an owner for sections within a GROUP: The 

entire group is treated as one unit, so the group may be aligned or bound 
to an address, but the sections making up the group may not be handled 
individually. 

cannot specify a page for a section within a GROUP 

DSECT (...) can't be given an owner: Since dummy sections do 
not participate in memory allocation, it is meaningless for a dummy sec¬ 
tion to be given an owner or an attribute. 

DSECT (...) can't be linked to an attribute 

-e flag does not specify a legal symbol name (...) 

entry point other than — c~intOO specified: For -c option only. 

entry point symbol (...) undefined 

errors in input - (...) not built 

fill value on -f flag truncated to (...) bytes (warning) 

ifile (comfile) nesting exceeded with file (...): Command file 
nesting is allowed up to 16 levels. 

illegal operator in expression 

misuse of "." symbol in assignment instruction: The dot symbol 
cannot be used in assignment statements that are outside SECTIONS 
directives. 

no input files 

number (...) not a power of 2: For the ALIGN operator. 

-o flag does specify a valid file name : string 
option flag does not specify a number 
option is invalid flag 

section (...) not built: The most likely cause of this is a syntax error 
in the SECTIONS directive. 

semicolon required after expression 

statement ignored: Caused by a syntax error in a expression. 

symbol referencing errors - (...) not built 

symbol (...) from file (...) being redefined: A defined symbol may 
not be redefined in an assignment statement. 

syntax error: scanned line = (...) 
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unexpected EOF(end of file): Syntax error in the linker command 
file. 

undefined symbol in expression 
• Allocation Errors 

These error messages appear during the allocation phase of linking. 
They generally appear if a section or group does not fit at a certain ad¬ 
dress or if the MEMORY and SECTION directives conflict in some way. 
If you are using a linker command file, check that MEMORY and SEC¬ 
TION directives allow enough room to ensure that no sections overlap 
and that no sections are being placed in unconfigured memory. 

binding address (...) for section (...) is outside all memory on 
page (...) 

binding address (...) for section (...) overlays previously allo¬ 
cated section 

binding address (...) incompatible with alignment for section 

(...) 

can't allocate output section, (...) of size (...) on page (...) 

can't allocate section (...) with attribute (...) on page (...) 

default allocation failed: (...) is too large 

GROUP containing section (...) is too big 

internal symbol (...) redefined in file (...): Ignored. 

memory types (...) and (...) on page (...) overlap 

no owner (...) for section (...) on page (...): Invalid or nonexistent 
memory range. 

output file (...) not executable (warning) 

PC-relative displacement overflow at address (...) in file (...) 

section (...) at address (...) overlays previously allocated sec¬ 
tion (...) at address 

section (...), bound at address (...), won't fit into page (...) of 
configured memory 

section (...) enters unconfigured memory at address (...) 
section (...) in file (...) is too big 

undefined symbol (...) first referenced in file (...): Unless the -r 
option is used, the linker requires that all referenced symbols are defined. 
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• I/O Errors: 

The following error messages indicate that the input file is corrupt, no¬ 
nexistent, or unreadable or because the linker cannot write to the output 
file. Make sure that the input file is in the correct directory and that the 
file system is not out of space. If the input file is corrupt, try reassem¬ 
bling it. 

cannot complete output file (...), write error 

cannot create output file (...): 

can't open (...) 

can't read (...) 

can't seek (...) 

could not create map file (...) 

fail to copy (...) 

fail to read (...) 

fail to seek (...) 

fail to skip (...) 

fail to write (...) 

file (...) has no relocation information 

file (...) is of unknown type, magic number = (...) 

illegal relocation type (...) found in section(s) of file (...) 

internal error : aux table overflow 

invalid archive size for file (...) 

I/O error on output file (...) 

library (...) member has no relocation information 
line number entry found for absolute symbol 
memory allocation failure 

no symbol map produced - not enough memory 

relocation symbol not found: index (...), section (...), file (...) 

relocation entries out of order in section (...) of file (...) 

section (...) not found: An input section specified in a SECTIONS 
directive was not found in the input file. 

sections .text, .data, or .bss not found: Optional header may be 
useless. 

seek to (...) failed 
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Appendix F 

Glossary 


absolute address: An address that is permanently assigned to a 
TMS34010 memory location. 

alignment: A process in which the linker places an output section at an 
address that falls on an /7-bit boundary, where n is a power of 2. You can 
specify alignment with the SECTIONS linker directive. 

allocation: A process in which the linker calculates the final memory ad¬ 
dresses of output sections. 

archive library: A collection of individual files that have been grouped into 
a single file. 

archiver: A software program that allows you to collect several individual 
files into a single file called an archive library. The archiver also allows you 
to delete, extract, or replace members of the archive library, as well as add new 
members. 

assembler: A software program that creates a machine-language program 
from a source file that contains assembly language instructions, directives, and 
macro directives. The assembler substitutes absolute operation codes for 
symbolic operation codes, and absolute or relocatable addresses for symbolic 
addresses. 

assembly-time constant: A symbol that is assigned a constant value by 
the .set directive. 

assignment statement: A statement that assigns a value to a variable. 

autoinitialization: The process of initializing global C variables (contained 
in the .cinit section) before beginning program execution. 

auxiliary entry: A symbol may have an extra entry in the symbol table that 
contains additional information about the symbol (whether the symbol is a 
filename, as section name, a function name, etc.). 

binding: A process in which you specify a distinct address for an output 
section or a symbol. 

block: A set of declarations and statements that are grouped together with 
braces. 

.bss: This is one of the default COFF sections. You can use the .bss direc¬ 
tive to reserve a specified amount of space in the memory map that can later 
be used for storing data. The .bss section is uninitialized. 
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cache memory: A fast local memory onboard the TMS34010. Blocks of 
code that are executed repeatedly can be loaded into the cache; this reduces 
the number of memory cycles and speeds program execution. 

command file: A file that contains linker options and names input files for 
the linker. 

comment: A source statement (or portion of a source statement) that is 
used to document or improve readability of a source file. Comment are not 
compiled, assembled, or linked; they have no effect on the object file. 

common object file format (COFF): An object file that promotes mod¬ 
ular programming by supporting the concept of sections. 

conditional processing: A method of processing one block of source 
code or an alternate block of source code, based upon the evaluation of a 
specified expression. 

configured memory: Memory that the linker has defined for allocation. 
By default, all memory is configured; you can configure specific ranges of 
memory with the MEMORY linker directive. 

constant: A numeric value that can be used as an operand. 

cross-reference listing: An output file created by the assembler that lists 
the symbols that were defined, what line they were defined on, which lines 
referenced them, and their final values. 

.data: This is one of the default COFF sections. The .data section is an ini¬ 
tialized section that contains initialized data. You can use the .data directive 
to assemble code into the .data section. 

directive: Special-purpose commands that control the actions and func¬ 
tions of a software tool (as opposed to assembly language instructions, which 
control the actions of a device). 

emulator: A hardware development system that emulates TMS34010 op¬ 
eration. 

entry point: The starting execution point in target memory. 

executable module: An object file that has been linked and can be exe¬ 
cuted in a TMS34010 system. 

expression: A constant, a symbol, or a series of constants and symbols se¬ 
parated by arithmetic operators. 

external symbol: A symbol that is used in the current module but defined 
in another module, or, a symbol that is defined in the current module that can 
be referenced by other modules. 

field: For the TMS34010, a software-configurable data type whose length 
can be programmed to be any value in the range of 1-32 bits. 

file header: A portion of a COFF object file that contains general informa¬ 
tion about the object file (such as the number of section headers, the type of 
system the object file can be downloaded to, the number of symbols in the 
symbol table, and the symbol table's starting address). 
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global: Describes a symbol that is either 1) defined in the current module 
and accessed in another, or 2) accessed in the current module but defined in 
another. 

GROUP: An option of the SECTIONS directive that forces specified output 
sections to be allocated contiguously (as a group). 

GSP: TMS34010 graphics system processor. 

high-level language debugging: The ability of a compiler to retain sym¬ 
bolic and high-level language information (such as type and function defi¬ 
nitions) so that a debugging tool can use this information. 

hole: An area between the input sections that comprise an output section 
which contains no actual code or data. 

incremental linking: Linking files that have already been linked. 

initialized section: A COFF section that contains executable code or ini¬ 
tialized data. These sections can be built up with the .data, .text, or .sect di¬ 
rective. 

input section: A section from an object file that will be linked into an ex¬ 
ecutable module. 

label: A symbol which begins in column 1 of a source statement. 

line number entry: An entry in a COFF output module that maps lines of 
assembly code back to the original C source file that created them. 

linker: A software tool that combines object files to form an object module 
that can be allocated into TMS34010 system memory and executed by the 
TMS34010. 

listing file: An output file created by the assembler that lists source state¬ 
ments, their line numbers, and their effects on the SPC. 

loader: A device that loads an executable module into TMS34010 system 
memory. 

macro: A user-defined routine that can be used as an instruction, 
macro call: The process of invoking a macro. 

macro definition: A block of source statements that define the name and 
the code that make up a macro. 

macro expansion: The source statements that are substituted for the macro 
call and subsequently assembled. 

macro library: An archive library composed of macros. Each file in the li¬ 
brary must contain one macro; it's name must be the same as the macro name 
it defines, and it must have an extension of .asm. 

macro variable: A variable that is valid within a macro definition or during 
a macro expansion. 

magic number: An entry in the COFF file header that identifies an object 
file as a module that can be executed by the TMS34010. 
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map file: An output file created by the linker that shows the memory con¬ 
figuration, section composition and allocation, and symbols and the addresses 
at which they were defined. 

member: (1) An element or variable of a structure, union, or enumeration. 
(2) An individual file within an archive library. 

memory map: A map of TMS34010 target system memory space, which 
is partitioned into functional blocks. 

mnemonic: An instruction name that the assembler translates into machine 
code. 

model statement: Instructions or assembler directives in a macro defi¬ 
nition that are assembled each time a macro is invoked 

named section: A section that is defined with a .sect or .usect directive. 
The .sect directive defines initialized named sections that can be used like the 
.text and .data sections. The .usect directive defines uninitialized named sec¬ 
tions that can be used like the .bss section. 

object file: A file that has been assembled or linked and contains ma¬ 
chine-language object code. 

object format converter: A program that converts a COFF object file into 
an Intel, Tektronix, or Tl-tagged format object file. 

object library: An archive library made up of individual object files. 

operand: The arguments, or parameters, of an assembly language in¬ 
struction, assembler directive, or macro directive. 

optional header: A portion of a COFF object file that the linker uses to 
perform relocation at download time. 

options: Command parameters that allow you to request additional or spe¬ 
cific functions when you invoke a software tool. 

output module: A linked, executable object file that can be downloaded 
and executed on a target system. 

output section: A final, allocated section in a linked, executable module. 

overlay pages: Multiple areas of physical memory that overlay each other 
at the same address. A TMS34010 system can map different pages into the 
same address space in response to hardware select signals. 

partial linking: Linking a file that will be linked again. 

RAM model: An autoinitialization model used by the linker when linking 
C code. The linker uses this model when you invoke the linker with the -cr 
option. The RAM model allows variables to be initialized at load time instead 
of run time. 

raw data: Executable code or initialized data in an output section. 

relocation: A process in which the linker adjusts all the references to a 
symbol when the symbol's address changes. 
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ROM model: An autoinitialization model used by the linker when linking 
C code. The linker uses this model when you invoke the linker with the -c 
option. The ROM model tells the linker to load the .cinit section of data tables 
into memory; variables are initialized at run time. 

section: A relocatable block of code or data that will ultimately occupy 
contiguous space in the TMS34010 memory map. 

section program counter (SPC): An element of the assembler that keeps 
track of the current location within a section; each section has its own SPC. 

sign-extend: Fill unused MSBs of a value with the value's sign bit. 

simulator: A software development system that simulates TMS34010 op¬ 
eration. 

source file: A file that contains C code or TMS34010 assembly language 
code that will be compiled or assembled to form an object file. 

SPC: section program counter 

static: Refers to a variable whose scope is confined to a function or a pro¬ 
gram. The values of static variables are not discarded when the function or 
program is exited; their previous values are resumed when the function or 
program is re-entered. 

storage class: Any entry in the symbol table that indicates how a symbol 
should be accessed. 

string table: Symbol names that are longer than 8 characters cannot be 
stored in the symbol table; instead, they are stored in the string table. The 
name portion of the symbol's entry points to the location of the string in the 
string table. 

structure: A collection of one or more variables grouped together under a 
single name. 

symbol: A string of alphanumeric characters that represents an address or 
a value. 

symbolic debugging: The ability of a software tool to retain symbolic in¬ 
formation so that it can be used by a debugging tool such as a simulator or 
an emulator. 

symbol table: A portion of a COFF object file that contains information 
about the symbols that are defined and used by the file. 

tag: An optional "type" name that can be assigned to a structure, union, or 
enumeration. 

target memory: Physical memory in a TMS34010-based system into 
which executable object code will be loaded. 

.text: One of the default COFF sections. The .text section is an initialized 
section that contains executable code. You can use the .text directive to as¬ 
semble code into the .text section. 
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unconfigured memory: Memory that is not defined as part of the 
TMS34010 memory map and cannot be loaded with code or data. 

uninitialized section: A COFF section that reserves space in the 
TMS34010 memory map but that has no actual contents. These sections are 
built up with the .bss and .usect directives. 

union: A variable which may hold (at different times) object of different 
types and sizes. 

unsigned: Refers to a value that is treated as a positive number, regardless 
of its actual sign. 

well-defined expression: An expression that contains only symbols or 
assembly-time constants that have been defined before they appear in the 
expression. 

word: A 32-bit addressable location in target memory. 
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cross-reference listings 4-17 
directives 5-1-5-48 
error messages C-1 -C-4 
expressions 4-12-4-14 
in the development flow 1 -2, 4-2 
instruction set 6-1 -6-33 
invocation 4-3 
macros 7-1-7-9 


output 4-15-4-17, 5-11,5-18, 5-31, 
5-34, 5-36, 5-37, 5-38, 5-44 
overview 4-1 
relocation 3-15 
sections 3-3-3-8 
source listings 4-15-4-17 
source statement format 4-6-4-7 
symbols 3-17,4-11 
assembler directives 5-1,5-48 

conditional assembly directives 5-12 
.else 5-30,5-12 
.endif 5-30,5-12 
.if 5-30,5-12 
sections directives 3-3-3-8 
.bss 5-16, 3-3-3-8, 5-4 
.data 5-20, 3-3-3-8, 5-4 
.sect 5-39, 3-3-3-8, 5-4 
.text 5-43, 3-3-3-8, 5-4 
.usect 5-45, 3-3-3-8, 5-4 
summary table 5-2-5-3 
symbolic debugging directives B-1 - 
B-11 

.block/.endblock B-2, B-1 

.etag/.eos B-8, B-1 
.file B-3, B-1 
.func/.endfunc B-4, B-1 
.line B-6, B-1 
.member B-7, B-1 
.stag/.eos B-8, B-1 
.sym B-10, B-1 
.utag/.eos B-8, B-1 
that align the SPC 5-9 
.align 5-15, 5-9 
.even 5-9, 5-23 

that format the output listing 5-11 
.length 5-31,5-11 
.list 5-32,5-11 
.mlist 5-36,5-11 
.mnolist 5-36,5-11 
.nolist 5-32,5-11 
.option 5-37,5-11 
.page 5-38,5-11 
.title 5-44,5-11 
.width 5-31,5-11 
that initialize constants 5-6 
.bes 5-41,5-6 
.byte 5-17,5-6 
.double 5-21,5-6 
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.field 5-25, 5-6 
.float 5-6, 5-27 
.int 5-33, 5-6 
.long 5-33, 5-6 
.set 5-40, 5-6 
.space 5-41,5-6 
.string 5-42, 5-6 
.word 5-47, 5-6 
that reference other files 5-13 
.copy 5-18, 5-13, 5-19 
.def 5-28 
.end 5-22 
.file 5-13 
.global 5-28,5-13 
.include 5-18,5-19 
.mlib 5-34 
.ref 5-28 

assembly language development 
flow 1 -2, 4-2, 8-2, 9-2, 10-2, 11 -2 
assembly-time constants 4-10,5-40 
assigning a value to a symbol 5-40 
autoinitialization 9-38, 9-40 
RAM model 9-6, 9-38-9-40 
ROM model 9-6, 9-38-9-40 
auxiliary entries A-20 
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-b option (assembler) 4-3 
.bes (assembler directive) 5-41, 5-6 
binary constants 4-8 
binding 9-20 

.block (assembler directive) B-2, B-1 
block definitions A-14, A-22, A-23, B-2 
boot.obj 9-38 

.bss (assembler directive) 5-16, 3-3-3-8, 
5-4 

.bss section 3-3-3-14, 5-4, 5-1 6, 9-33, 
A-3 

initialization 9-36 

.byte (assembler directive) 5-17, 5-6 
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C compiler 1-3,1-6,9-6,9-38-9-40, 
B-1 -B-11 

block definitions B-2 
enumeration definitions B-8 
file identification B-3 
function definitions B-4 
line number entries B-6 


linking C code 9-38 
member definitions B-7 
structure definitions B-8 
symbol table entries B-10 
union definitions B-8 
-c option (assembler) 4-3 
-c option (linker) 9-6, 9-38-9-40 
cache alignment 5-10,5-15 
C—DIR (environment variable) 9-7 
character constants 4-10 
character set E-1 
character strings 4-11 
.cinit section 9-29, 9-38, 9-39, 9-40 
—c—intOO (entry point for C code) 9-6, 
9-40 

code conversion 10-1 -10-4 
COFF 1-1, 3-1-3-17, A-1-A-23 
auxiliary entries A-20 
file headers A-4 
file structure A-2 
line number entries A-10, B-6 
relocation information A-8 
section headers A-6 
sections 3-1-3-17 
special symbols A-13 
string table A-15 
symbol table A-12 
command files (linker) 9-3,9-11 
example 9-42 
comments 

in assembler source 4-7 
in linker command files 9-11 
common object file format 
See COFF 

compare instructions 6-22 
conditional blocks 5-12, 7-7 

assembler directives 5-12, 5-30 
macro directives 7-7 
conditional expressions 4-13 
configured memory 9-14, 9-27 
constants 4-8-4-10 

assembly-time constants 4-10, 5-40 

binary integers 4-8 

characters 4-10 

decimal integers 4-9, 9-31 

floating point 5-27 

hexadecimal integers 4-9, 9-31 

linker 9-31 

octal integers 4-8, 9-31 
XY 4-9 

context switching instructions 6-29 
.copy (assembler directive) 5-18, 4-4, 
5-13, 5-19 

copy files 4-4,5-18 
COPY section 9-29 
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-cr option (linker) 9-6, 9-38-9-40 
cross-reference listings 4-17 
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d command (archiver) 8-3 
.data (assembler directive) 5-20, 3-3- 
3-8, 5-4 

.data section 3-3-3-14, 5-4, 5-20, 9-33, 
A-3 

decimal constants 4-9, 9-31 

.def (assembler directive) 5-28 

default allocation 3-9 

default fill value for holes 9-6, 9-33 

default sections 3-2-3-14, 5-20, 5-43 

defining macros 7-4 

development tools overview 1 -2 

direct operands 6-2 

directives 

See assembler directives 
.double (assembler directive) 5-21,5-6 
DSECT section 9-29 
dummy section 9-29 
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e option (archiver) 8-3 
-e option (linker) 9-6 
.else (assembler directive) 5-30, 5-12 
$ELSE (macro directive) 7-2, 7-7 
emulator 1 -3 

.end (assembler directive) 5-22 
.endblock (assembler directive) B-2, B-1 
.endfunc (assembler directive) B-4, B-4, 
B-1 

.endif (assembler directive) 5-30, 5-12 
$ENDIF (macro directive) 7-2, 7-7 
$ENDLOOP (macro directive) 7-2, 7-8 
$ENDM (macro directive) 7-2 
entry points for the linker 9-6 
for C code 9-40 
enumeration definitions B-8 
environment variables 

A—DIR (assembler) 4-4, 4-5 
C-DIR (linker) 9-7, 9-8 
.eos (assembler directive) B-8, B-1 
EPROM programmers 1 -3, 10-1 
error messages 

assembler C-1-C-4 


linker D-1-D-4 

.etag (assembler directive) B-8, B-1 
.even (assembler directive) 5-23, 5-9 
expressions 4-12-4-14,9-30 
conditional 4-13 
examples 4-13 
that are well defined 4-13 
that contain arithmetic 
operators 4-12 
that contain relocatable 
symbols 4-13 
underflow/underflow 4-13 
external symbols 3-17, 4-13, 5-13, 5-28, 
5-40, 9-7 


F 


-f option (linker) 9-6 

-f option (simulator) 11-3 

.field (assembler directive) 5-25, 5-6 

.file (assembler directive) B-3, 5-13, B-1 

file headers A-4 

file identification B-3 

flib.lib 9-38 

.float (assembler directive) 5-27, 5-6 
floating point 5-21,5-27 
font library 1-6 

.func (assembler directive) B-4, B-1 
function definitions A-14, A-22, A-23, 
B-4 
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.global (assembler directive) 5-28,3-17, 
5-13 

global symbols 3-17, 4-13, 5-13, 5-28, 
9-7 

graphics instructions 6-26 
GROUP option (SECTIONS 
directive) 9-22 
GSP 

See TMS34010 
gspa command 4-3 
gspar command 8-3 
gsplnk command 9-3 

command options summary 9-4 
gsprom command 10-3 
gspsim/gspsimt commands 11 -3 
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~h option (assembler) 4-3 
-h option (linker) 9-7 
hexadecimal constants 4-9, 9-31 
hi-bytefile 10-3 
holes 9-6, 9-33 

in output sections 9-33 
how to use this manual 1 -5 
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-i option (assembler) 4-3, 4-4 
-i option (linker) 9-7 
-i option (object format converter) 10-3 
.if (assembler directive) 5-30, 5-12 
$IF (macro directive) 7-2, 7-7 
immediate operands 6-2 
.include (assembler directive) 5-18, 4-4, 
5-19 

include files 4-4, 5-18 
incremental linking 9-37 
indirect operands 6-3, 6-4 
in XY mode 6-4 
with offset 6-3 
with postincrement 6-3 
with predecrement 6-4 
initialized sections 3-2, 3-4, 5-20, 5-39, 
5-43, 9-33 
input 

archiver 8-1 
assembler 8-1 

linker 8-1,9-2, 9-13, 9-41,9-42 
object format converter 10-1 
simulator 11-3, 11-18 
instruction set 1 -6, 6-1 -6-33 
arithmetic instructions 6-22 
compare instructions 6-22 
condition codes 6-31 
graphics instructions 6-26 
jump instructions 6-30 
logical instructions 6-22 
move instructions 6-24 
operand formats 6-2 
program control instructions 6-29 
shift instructions 6-32 
summary table 6-5-6-21 
.int (assembler directive) 5-33, 5-6 
integers 

See constants 

Intel object format 10-1,10-3 
invoking the ... 


archiver 8-3 
assembler 1 -4, 4-3 
linker 1-4, 9-3 
object format converter 10-3 
simulator 11-3 


J 


jump instructions 6-30 
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-I option (assembler) 4-3 
-I option (linker) 9-7 
labels 4-6, 4-7, 7-9 
.length (assembler directive) 5-31,5-11 
.line (assembler directive) B-6, B-1 
line number entries A-10, B-6 
linker 1 -3, 9-1 -9-43 
COFF 3-9-3-14,9-1 
command files 3-12,9-3,9-11,9-42 
command options 
summary 9-4-9-10 
configured memory 9-14 
error messages D-1 -D-4 
example 9-41 -9-43 
expressions 9-30 
gsplnk command 9-3 
in the development flow 1 -2, 9-2 
input 9-2, 9-13, 9-41, 9-42 
invocation 9-3 
linking C code 9-38-9-40 
loading a program 3-16 
map files 9-9, 9-43 
operators 9-32 
output 9-2, 9-9, 9-41, 9-43 
relocation 3-15 
sections 3-9-3-14 
SECTIONS directive 9-16 
symbols 3-17 
unconfigured memory 9-14 
linking C code 9-6, 9-38-9-40 
.list (assembler directive) 5-32, 5-11 
listing control 5-32, 5-36, 5-37, 5-44 
listing file 5-11 
listing page size 5-31 
loading a program 3-16 
lo-bytefile 10-3 
logical instructions 6-22 
.long (assembler directive) 5-33, 5-6 
$LOOP (macro directive) 7-2, 7-8 
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-m option (linker) 9-9 
machine-state display 11-5 
MACLIB files 5-34, 7-3 
$MACRO (macro directive) 7-2, 7-4 
macro libraries 4-4, 5-34, 7-3, 8-1 
macros 7-1, 7-9 
calls 7-1 

conditional blocks 7-7 
definitions 7-4 
directives summary 7-2 
MACLIB files 5-34, 7-3 
macro libraries 5-34, 7-3 
.mlib directive 5-34, 7-3 
parameters 7-6 
redefining opcodes 7-5 
repeatable blocks 7-8 
substitution 7-1 
unique labels 7-9 
—main (entry point) 9-6 
manual organization 1-5 
map files 9-9 
example 9-43 

.member (assembler directive) B-7, B-1 
member definitions B-7 
MEMORY (linker directive) 3-9-3-14, 
9-14 

default model 3-9-3-12,9-14 
examples 3-12-3-14 
overlay pages 9-23 
syntax 9-14 

.mlib (assembler directive) 5-34, 4-4, 
5-13, 7-3 

.mlist (assembler directive) 5-36, 5-11 
mnemonics 4-1,4-6 
.mnolist (assembler directive) 5-36, 5-11 
move instructions 6-24 
MS-DOS software installation 2-2 
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named memory 9-21 
named sections 3-2-3-14, 5-4, 9-33, 
A-3 

See also Section 3.2.3 
.sect 3-3, 3-5, 5-39 
.usect 3-3, 3-5, 5-45 
naming an output module 9-9 
.nolist (assembler directive) 5-32, 5-11 
NOLOAD section 9-29 


O 

-o option (linker) 9-9 
object file format 
See COFF 

object format converter 1 -3, 10-1 -10-4 
examples 10-4 

in the development flow 1-2,10-2 
input 10-1, 10-3 
invocation 10-3 
output 10-1,10-3 
object formats 

See also COFF 
Intel object format 10-1 
Tektronix object format 10-1 
Tl-tagged object format 10-1 
object libraries 8-1, 9-7, 9-13, 9-38 
octal constants 4-8, 9-31 
opcodes 

redefining 7-5 
operands 4-7 

.option (assembler directive) 5-37,5-11 

optional file header A-5 

output 

archiver 8-1 

assembler 4-15-4-17,8-1 
linker 8-1,9-2, 9-9, 9-41,9-43 
object format converter 10-1 
output listing 5-11 
overflow (in expressions) 4-13 
overlay pages 9-23-9-26 
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.page (assembler directive) 5-38, 5-11 

partial linking 9-37 

PC-DOS software installation 2-2 

predefined symbols 4-11 

program control instructions 6-29 
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q option (archiver) 8-3 
-q option (assembler) 4-3 
-q option (linker) 9-9 
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r command (archiver) 8-3 
-r option (linker) 9-4, 9-37 
RAM model (C compiler) 9-6, 
9-38-9-40 

redefining opcodes 7-5 
.ref (assembler directive) 5-28 
register-direct operands 6-2 
related documentation 1 -6 
relocatable output module 9-5 
relocatable symbols 4-13 
relocation 3-1 5, 4-10, 9-4, 9-5, A-8 
repeatable blocks 7-8 
ROM model (C compiler) 9-6, 
9-38-9-40 
rts.lib 9-38 

runtime initialization 9-38 
runtime support 9-38 
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s option (archiver) 8-3 
-s option (assembler) 4-3 
-s option (linker) 9-10 
SDB 1-3, 1-6 

.sect (assembler directive) 5-39, 3-3- 
3-8, 5-4 

section headers A-6 
section specifications 9-17 
sections 1 -1, 3-1 -3-17 

.bss section 3-2-3-14, 5-16, 9-33 
.data section 3-2-3-14, 5-20 
default sections 3-2-3-14, 5-20, 
5-43 

directives 3-2-3-8, 5-4 
initialized sections 3-2-3-14, 5-20, 
5-39, 5-43 

named sections 3-2, 3-5, 5-39, 5-45 
.text section 3-2-3-14,5-43 
uninitialized sections 3-2-3-14, 

5-16, 5-45, 9-33 

SECTIONS (linker directive) 3-9-3-14, 
9-16 

alignment 9-20 
allocation 9-20, 9-27 
binding 9-20 

default allocation 3-9-3-12,9-27 
examples 3-12-3-14 
GROUP option 9-22 
named memory 9-21 
overlay pages 9-24 


section specifications 9-17 
syntax 9-16 

.set (assembler directive) 5-40, 5-6 
shift instructions 6-32 
simulator 1-3, 11-1-11-132 
command summary 11 -24 
in the development flow 1-2,11-2 
input 11-3, 11-18, 11-39, 11-72, 
11-116 

invocation 11-3 
machine-state display 11-5 
system requirements 11 -4 
software development board 1 -3, 1 -6 
software installation 2-1 

list of supported operating 
systems 2-1 
MS-DOS 2-2 
PC-DOS 2-2 
VAX/System V 2-4 
VAX/ULTRIX 2-4 
VAX/VMS 2-4 
source listings 4-15 
source statement format 4-6-4-7 
comment field 4-7 
label field 4-6 
mnemonic field 4-7 
operand field 4-7 

.space (assembler directive) 5-41,5-6 
SPC 3-6 

assembler symbol 4-11 
linker symbol 9-30 
special section types 9-29 
special symbols in the symbol table A-13 
.stag (assembler directive) B-8, B-1 
static symbols 9-7 
static variables A-12 
storage classes A-16 
.string (assembler directive) 5-42, 5-6 
string table A-1 5 
stripping line number entries 9-10 
stripping symbolic information 9-10 
structure definitions A-21,B-8 
style and symbol conventions 1 -7 
.sym (assembler directive) B-10, B-1 
symbol names A-15 
symbol table 3-17, A-12 
symbol table entries 3-17, B-10 
symbolic debugging 9-10, A-10, A-12, 
B-1 - B-11 

assembler directives 5-1, B-1 
block definitions B-2 
enumeration definitions B-8 
file identification B-3 
function definitions B-4 
line number entries B-6 
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member definitions B-7 
-s assembler option 4-3 
structure definitions B-8 
symbol table entries B-10 
union definitions B-8 
symbols 3-1 7, 4-11,5-40, 5-45 
character strings 4-11 
external 3-17, 5-13, 5-28, 5-40 
global 3-17, 5-13, 5-28 
predefined 4-11 
relocatable symbols in 
expressions 4-13 
relocation 3-15, A-8 
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t command (archiver) 8-3 
-t option (object format converter) 10-3 
-t option (simulator) 11-3 
Tektronix object format 10-1,10-3 
.text (assembler directive) 5-43, 3-3-3-8, 
5-4 

.text section 3-3-3-14, 5-4, 5-43, 9-33, 
A-3 

Tl-tagged object format 10-1, 10-3 
.title (assembler directive) 5-44, 5-11 
TMS34010 

definition 1-1 
support tools 1-1, 1-2 
TMS34010 archiver 
See archiver 
TMS34010 assembler 
See assembler 
TMS34010 linker 
See linker 

TMS34010 object format converter 
See object format converter 
TMS34010 simulator 
See simulator 
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-u option (linker) 9-10 
unconfigured memory 9-14,9-27 
underflow (in expressions) 4-13 
uninitialized sections 3-2, 3-4, 5-16, 
5-45, 9-33 

initialization 9-36 
union definitions B-8 
unique labels 7-9 

.usect (assembler directive) 5-45, 3-3- 
3-8, 5-4 

.utag (assembler directive) B-8, B-1 
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v option (archiver) 8-3 
VAX/System V software installation 2-4 
VAX/ULTRIX software installation 2-4 
VAX/VMS software installation 2-4 


w 

well-defined expressions 4-13 
.width (assembler directive) 5-31,5-11 
.word (assembler directive) 5-47, 5-6 
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x command (archiver) 8-3 

-x option (assembler) 4-3 

-x option (object format converter) 10-3 

XDS/22 emulator 1-3 

XY constants 4-9 
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Kierulff (408)971-2600; Marshall (408) 942-4600; 
Schweber (408) 432-7171; Wyle (408) 727-2500 
Zeus (408) 998-5121 

COLORADO: Arrow (303) 696-1111; 

Hall-Mark (303) 790-1662; Kierulff (303) 790-4444; 
Marshall (303) 451-8444; Schweber (303) 799-0258 
Wyle (303) 457-9953 

CONNECTICUT: Arrow (203) 265-7741; 

Hall-Mark (203) 269-0100; Kierulff (203) 265-1115; 
Marshall (203) 265-3822; Schweber (203) 748-7080 

FLORIDA: Ft. Lauderdale: Arrow (305) 429-8200; 
Hall-Mark (305) 971-9280; Kierulff (305) 486-4004 
Marshall (305) 977-4880; Schweber (305) 977-7511; 
Orlando: Arrow (305) 725-1480; 

Hall-Mark (305) 855-4020; Kierulff (305) 682-6923 
Marshall (305) 841-1878, Schweber (305) 331-7555 
Zeus (305) 365-3000; 

Tampa: Hall-Mark (813) 530-4543; 

Marshall (813) 576-1399 

GEORGIA: Arrow (404) 449-8252 

Hall-Mark (404) 447-8000; Kierulff (404) 447-5252 

Marshall (404) 923-5750; Schweber (404) 449-9170 

ILLINOIS: Arrow (312) 397-3440; 

Hall-Mark (312) 860-3800; Kierulff (312) 250-0500; 
Marshall (312) 490-0155; Newark (312) 784-5100; 
Schweber (312) 364-3750. 

INDIANA: Indianapolis: Arrow (317) 243-9353; 
Hall-Mark (317) 872-8875; Marshall (317) 297-0483 


MARYLAND: Arrow (301) 995-0003, 

Hall-Mark (301) 988-9800, Kierulff (301) 840-1155. 
Marshall (301) 840-9450; Schweber (301) 840-5900; 
Zeus (301) 997-1118 

MASSACHUSETTS: Arrow (617) 933-8130, 
Hall-Mark (617) 667-0902; Kierulff (617) 667-8331; 
Marshall (617) 658-0810; Schweber (617) 275-5100. 
(617) 657-0760; Time (617) 532-6200; 

Zeus (617) 863-8800 

MICHIGAN: Detroit: Arrow (313) 971-8220; 
Marshall (313) 525-5850; Newark (313) 967-0600; 
Schweber (313) 525-8100; 

Grand Rapids: Arrow (616) 243-0912 

MINNESOTA: Arrow (612) 830-1800; 

Hall-Mark (612) 941-2600; Kierulff (612) 941-7500; 
Marshall (612) 559-2211; Schweber (612) 941-5280 

MISSOURI: St. Louis: Arrow (314) 567-6888; 
Hall-Mark (314) 291-5350; Kierulff (314) 997-4956: 
Schweber (314) 739-0526. 

NEW HAMPSHIRE: Arrow (603) 668-6968; 
Schweber (603) 625-2250. 

NEW JERSEY: Arrow (201) 575-5300, 

(609) 596-8000; General Radio (609) 964-8560; 
Hall-Mark (201) 575-4415, (609) 235-1900; 

Kierulff (201) 575-6750, (609) 235-1444; 

Marshall (201) 882-0320, (609) 234-9100; 

Schweber (201) 227-7880 


Hall-Mark (516) 737-0600; Marshall (516) 273-2053; 
Schweber (516) 334-7555; Zeus (914) 937-7400 
Rochester: Arrow (716) 427-0300; 

Hall-Mark (716) 244-9290; Marshall (716) 235-7620; 
Schweber (716) 424-2222. 

Syracuse: Marshall (607) 798-1611 

NORTH CAROLINA: Arrow (919) 876 3132, 

(919) 725-8711; Hall-Mark (919) 872-0712; 

Kierulff (919) 872-8410; Marshall (919) 878-9882; 
Schweber (919) 876-0000. 

OHIO: Cleveland: Arrow (216) 248-3990; 

Hall-Mark (216) 349-4632; Kierulff (216) 831-5222; 
Marshall (216) 248-1788; Schweber (216) 464-2970 
Columbus: Arrow (614) 885-8362; 

Hall-Mark (614) 888-3313; 

Dayton: Arrow (513) 435-5563; 

Kierulff (513) 439-0045; Marshall (513) 236-8088; 
Schweber (513) 439-1800. 


OREGON: Arrow (503) 684-1690; 

Kierulff (503) 641-9153; Wyle (503) 640-6000; 
Marshall (503) 644-5050. 

PENNSYLVANIA: Arrow (412) 856-7000, 

(215) 928-1800; General Radio (215) 922-7037; 
Schweber (215) 441-0600, (412) 782-1600. 

TEXAS: Austin: Arrow (512) 835-4180; 

Hall-Mark (512) 258-8848; Kierulff (512) 835-2090; 
Marshall (512) 837-1991; Schweber (512) 458-8253; 
Wyle (512) 834-9957; 

Dallas: Arrow (214) 380-6464; 

Hall-Mark (214) 553-4300; Kierulff (214) 840-0110; 
Marshall (214) 233-5200; Schweber (214) 661-5010; 
Wyle (214) 235-9953; Zeus (214) 783-7010; 
Houston: Arrow (713) 530-4700; 

Hall-Mark (713) 781-6100; Kierulff (713) 530-7030; 
Marshall (713) 895-9200; Schweber (713) 784-3600; 
Wyle (713) 879-9953 

UTAH: Arrow (801) 972-0404; 

Hall-Mark (801) 972-1008; Kierulff (801) 973-6913; 
Marshall (801) 485-1551; Wyle (801) 974-9953 

WASHINGTON: Arrow (206) 643-4800; 

Kierulff (206) 575-4420; Wyle (206) 453-8300; 
Marshall (206) 747-9100. 

WISCONSIN: Arrow (414) 792-0150; 

Hall-Mark (414) 797-7844, Kierulff (414) 784-8160; 
Marshall (414) 797-8400; Schweber (414) 784-9020 

CANADA: Calgary: Future (403) 235-5325; 
Edmonton: Future (403) 438-2858; 

Montreal: Arrow Canada (514) 735-5511; 

Future (514) 694-7710; 

Ottawa: Arrow Canada (613) 226-6903; 

Future (613) 820-8313; 

Quebec City: Arrow Canada (418) 687-4231; 
Toronto: Arrow Canada (416) 672-7769; 

Future (416) 638-4771; 

Vancouver: Future (604) 294-1166; 

Winnipeg: Future (204) 339-0554 
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ALABAMA: Huntsville: 500 Wynn Drive, Suite 514, 
Huntsville, AL 35805, (205) 837-7530. 

ARIZONA: Phoenix: 8825 N. 23rd Ave., Phoenix, 

AZ 85021, (602) 995-1007. 

CALIFORNIA: Irvine: 17891 Cartwright Rd., Irvine, 

CA 92714, (714) 660-8187; Sacramento: 1900 Point 
West Way, Suite 171, Sacramento, CA 95815, 

(916) 929-1521; San Diego: 4333 View Ridge Ave., 
Suite B„ San Diego, CA 92123, (619) 278-9601; 

Santa Clara: 5353 Betsy Ross Dr., Santa Clara, CA 
95054, (408) 980-9000; Torrance: 690 Knox St., 
Torrance, CA 90502, (213) 217-7010; 

Woodland Hills: 21220 Erwin St., Woodland Hills, 

CA 91367, (818) 704-7759. 

COLORADO: Aurora: 1400 S Potomac Ave , 

Suite 101, Aurora, CO 80012, (303) 368-8000 

CONNECTICUT: Wallingford: 9 Barnes Industrial 
Park Rd., Barnes Industrial Park, Wallingford, 

CT 06492, (203) 269-0074. 

FLORIDA: Ft. Lauderdale: 2765 N.W. 62nd St., 

Ft. Lauderdale, FL 33309, (305) 973-8502; 

Maitland: 2601 Maitland Center Parkway, 

Maitland, FL 32751, (305) 660-4600; 

Tampa: 5010 W. Kennedy Blvd., Suite 101, 

Tampa, FL 33609, (813) 870-6420. 

GEORGIA: Norcross: 5515 Spalding Drive, Norcross. 
GA 30092, (404) 662-7900 

ILLINOIS: Arlington Heights: 515 W Algonquin, 
Arlington Heights, IL 60005, (312) 640-2925. 

INDIANA: Ft. Wayne: 2020 Inwood Dr., Ft. Wayne, 

IN 46815, (219) 424-5174; 

Indianapolis: 2346 S. Lynhurst, Suite J-400, 
Indianapolis, IN 46241, (317) 248-8555. 

IOWA: Cedar Rapids: 373 Collins Rd. NE, Suite 200, 
Cedar Rapids, IA 52402, (319) 395-9550. 

MARYLAND: Baltimore: 1 Rutherford PI., 

7133 Rutherford Rd., Baltimore, MD 21207, 

(301) 944-8600. 

MASSACHUSETTS: Waltham: 504 Totten Pond Rd., 
Waltham, MA 02154, (617) 895-9100. 

MICHIGAN: Farmington Hills: 33737 W 12 Mile Rd., 
Farmington Hills, Ml 48018, (313) 553-1500. 

MINNESOTA: Eden Prairie: 11000 W. 78th St., 

Eden Prairie, MN 55344 (612) 828-9300. 

MISSOURI: Kansas City: 8080 Ward Pkwy., Kansas 
City, MO 64114, (816) 523-2500; 

St. Louis: 11816 Borman Drive, St. Louis, 

MO 63146, (314) 569-7600. 

NEW JERSEY: Iselin: 485E U.S. Route 1 South, 
Parkway Towers, Iselin, NJ 08830 (201) 750-1050 

NEW MEXICO: Albuquerque: 2820-D Broadbent Pkwy 
NE, Albuquerque, NM 87107, (505) 345-2555. 

NEW YORK: East Syracuse: 6365 Collamer Dr., East 
Syracuse, NY 13057, (315) 463-9291; 

Endicott: 112 Nanticoke Ave., P.O. Box 618, Endicott, 
NY 13760, (607) 754-3900; Melville: 1 Huntington 
Quadrangle, Suite 3C10, P.O. Box 2936, Melville, 

NY 11747, (516) 454-6600; Pittstord: 2851 Clover St., 
Pittsford, NY 14534, (716) 385-6770; 

Poughkeepsie: 385 South Rd., Poughkeepsie, 

NY 12601, (914) 473-2900. 

NORTH CAROLINA: Charlotte: 8 Woodlawn Green, 
Woodlawn Rd., Charlotte, NC 28210, (704) 527-0930; 
Raleigh: 2809 Highwoods Blvd., Suite 100, Raleigh, 
NC 27625, (919) 876-2725. 

OHIO: Beachwood: 23408 Commerce Park Rd., 
Beachwood, OH 44122, (216) 464-6100; 

Dayton: Kingsley Bldg., 4124 Linden Ave., Dayton, 
OH 45432, (513) 258-3877. 

OREGON: Beaverton: 6700 SW 105th St., Suite 110, 
Beaverton, OR 97005, (503) 643-6758. 


PENNSYLVANIA: Ft. Washington: 260 New York Dr., 
Ft. Washington, PA 19034, (215) 643-6450; 
Coraopolis: 420 Rouser Rd., 3 Airport Office Park, 
Coraopolis, PA 15108, (412) 771-8550. 

PUERTO RICO: Hato Rey: Mercantil Plaza Bldg., 
Suite 505, Hato Rey, PR 00919, (809) 753-8700. 

TEXAS: Austin: P.O. Box 2909, Austin, TX 78769, 
(512) 250-7655; Richardson: 1001 E, Campbell Rd., 
Richardson, TX 75080, 

(214) 680-5082; Houston: 9100 Southwest Frwy., 

Suite 237, Houston, TX 77036, (713) 778-6592; 

San Antonio: 1000 Central Parkway South, 

San Antonio, TX 78232, (512) 496-1779. 

UTAH: Murray: 5201 South Green SE, Suite 200, 
Murray, UT 84107, (801) 266-8972. 

VIRGINIA: Fairfax: 2750 Prosperity, Fairfax, VA 
22031, (703) 849-1400. 

WASHINGTON: Redmond: 5010 148th NE, Bldg B, 
Suite 107, Redmond, WA 98052, (206) 881-3080 

WISCONSIN: Brookfield: 450 N Sunny Slope, 

Suite 150, Brookfield, Wl 53005, (414) 785-7140 

CANADA: Nepean: 301 Moodie Drive, Mallorn 
Center, Nepean, Ontario, Canada, K2H9C4, 

(613) 726-1970 Richmond Hill: 280 Centre St. E„ 
Richmond Hill L4C1B1, Ontario, Canada 
(416) 884-9181; St. Laurent: Ville St. Laurent Quebec, 
9460 Trans Canada Hwy., St. Laurent, Quebec, 
Canada H4S1R7, (514) 335-8392. 


ARGENTINA: Texas Instruments Argentina 
S.A.I.C.F.: Esmeralda 130, 15th Floor, 1035 Buenos 
Aires, Argentina, 1 +394-3008 

AUSTRALIA <& NEW ZEALAND): Texas Instruments 
Australia Ltd.: 6-10 Talavera Rd., North Ryde 
(Sydney), New South Wales, Australia 2113, 

2 + 887-1122; 5th Floor, 418 St. Kilda Road, 
Melbourne, Victoria, Australia 3004, 3 + 267-4677; 

171 Philip Highway, Elizabeth, South Australia 5112, 
8 + 255-2066. 

AUSTRIA: Texas Instruments Ges.m.b.H : 
Industriestrabe B/16, A-2345 Brunn/Gebirge, 
2236-846210. 

BELGIUM: Texas Instruments N.V. Belgium S.A.: 
Mercure Centre, Raketstraat 100, Rue de la Fusee, 
1130 Brussels, Belgium, 2/720.80.00. 

BRAZIL: Texas Instruments Electronicos do Brasil 
Ltda.: Rua Paes Leme, 524-7 Andar Pinheiros, 05424 
Sao Paulo, Brazil, 0815-6166. 

DENMARK: Texas Instruments A/S, Mairelundvej 
46E, DK-2730 Herlev, Denmark, 2 - 91 74 00 

FINLAND: Texas Instruments Finland OY: 
Teollisuuskatu 19D 00511 Helsinki 51, Finland, (90) 
701-3133. 

FRANCE: Texas Instruments France: Headquarters 
and Prod Plant, BP 05, 06270 Villeneuve-Loubet, 

(93) 20-01-01; Paris Office, BP 67 8-10 Avenue 
Morane-Saulnier, 78141 Velizy-Villacoublay, 

(3) 946-97-12, Lyon Sales Office, L'Oree D'Ecully, 
Batiment B, Chemin de la Forestiere, 69130 Ecully, 
(7) 833-04-40; Strasbourg Sales Office, Le Sebastopol 
3, Quai Kleber, 67055 Strasbourg Cedex, 

(88) 22-12-66; Rennes, 23-25 Rue du Puits Mauger, 
35100 Rennes, (99) 31-54-86; Toulouse Sales Office, 
Le Peripole—2, Chemin du Pigeonnier de la Cepiere, 
31100 Toulouse, (61) 44-18-19; Marseille Sales Office, 
Noilly Paradis—146 Rue Paradis, 13006 Marseille, 
(91) 37-25-30. 
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GERMANY (Fed. Republic of Germany): Texas 
Instruments Deutschland GmbH: Haggertystrasse 1, 
D-8050 Freising, 8161 +80-4591; Kurfuerstendamm 
195/196, D-1000 Berlin 15, 30 + 882-7365; III, Hagen 
43/Kibbelstrasse, .19, D-4300 Essen, 201-24250; 
Frankfurter Allee 6-8, D-6236 Eschborm 1, 

06196 + 8070; Hamburgerstrasse 11, D-2000 Hamburg 
76, 040 + 220-1154, Kirchhorsterstrasse 2, D-3000 
Hannover 51, 511 +648021; Maybachstrabe 11, 

D-7302 Ostfildern 2-Nelingen, 711 +547001; 

Mixikoring 19, D-2000 Hamburg 60, 40 + 637 + 0061; 
Postfach 1309, Roonstrasse 16, D-5400 Koblenz, 

261 + 35044. 

HONG KONG (+ PEOPLES REPUBLIC OF CHINA): 

Texas Instruments Asia Ltd., 8th Floor, World 
Shipping Ctr., Harbour City, 7 Canton Rd., Kowloon, 
Hong Kong, 3 + 722-1223. 

IRELAND: Texas Instruments (Ireland) Limited- 
Brewery Rd., Stillorgan, County Dublin, Eire, 

1 831311. 

ITALY: Texas Instruments Semiconduttori Italia Spa: 
Viale Delle Scienze, 1, 02015 Cittaducale (Rieti), 

Italy, 746 694.1; Via Salaria KM 24 (Palazzo Cosma), 
Monterotondo Scalo (Rome), Italy, 6 + 9003241; Viale 
Europa, 38-44, 20093 Cologno Monzese (Milano), 

2 2532541; Corso Svizzera, 185, 10100 Torino, Italy, 

11 774545; Via J. Barozzi 6, 40100 Bologna, Italy, 51 
355851. 

JAPAN: Texas Instruments Asia Ltd.: 4F Aoyama 
Fuji Bldg., 6-12, Kita Aoyama 3-Chome, Minato-ku, 
Tokyo, Japan 107, 3-498-2111; Osaka Branch, 5F, 
Nissho Iwai Bldg., 30 Imabashi 3- Chome, 

Higashi-ku, Osaka, Japan 541, 06-204-1881; Nagoya 
Branch, 7F Daini Toyota West Bldg., 10-27, Meieki 
4-Chome, Nakamura-ku Nagoya, Japan 
450, 52-583-8691. 

KOREA: Texas Instruments Supply Co.: 3rd Floor, 
Samon Bldg., Yuksam-Dong, Gangnam-ku, 

135 Seoul, Korea, 2 + 462-8001. 

MEXICO: Texas Instruments de Mexico S.A.: Mexico 
City, AV Reforma No. 450 — 10th Floor, Mexico, 

D.F., 06600, 5 + 514-3003. 

MIDDLE EAST: Texas Instruments: No. 13, 1st Floor 
Mannai Bldg., Diplomatic Area, P.O. Box 26335, 
Manama Bahrain, Arabian Gulf, 973 + 274681. 

NETHERLANDS: Texas Instruments Holland B.V., 

P.O. Box 12995, (Bullewijk) 1100 CB Amsterdam, 
Zuid-Oost, Holland 20 + 5602911. 

NORWAY: Texas Instruments Norway A/S: PB106, 
Refstad 131, Oslo 1, Norway, (2) 155090. 

PHILIPPINES: Texas Instruments Asia Ltd.: 14th 
Floor, Ba- Lepanto Bldg., 8747 Paseo de Roxas, 
Makati, Metro Manila, Philippines, 2 + 8188987. 

PORTUGAL: Texas Instruments Equipamento 
Electronico (Portugal), Lda.: Rua Eng. Frederico 
Ulrich, 2650 Moreira Da Maia, 4470 Maia, Portugal, 
2-948-1003. 

SINGAPORE (+ INDIA, INDONESIA, MALAYSIA, 
THAILAND): Texas Instruments Asia Ltd.. 12 Lorong 
Bakar Batu, Unit 01-02, Kolam Ayer Industrial Estate, 
Republic of Singapore, 747-2255. 

SPAIN: Texas Instruments Espana, S.A.: C/Jose 
Lazaro Galdiano No. 6, Madrid 16, 1/458.14.58. 

SWEDEN: Texas Instruments International Trade 
Corporation (Sverigefilialen): Box 39103, 10054 
Stockholm, Sweden, 8 - 235480. 

SWITZERLAND: Texas Instruments, Inc., Reidstrasse 
6, CH-8953 Dietikon (Zuerich) Switzerland, 

1-740 2220. 

TAIWAN: Texas Instruments Supply Co.; Room 903, 
205 Tun Hwan Rd., 71 Sung-Kiang Road, Taipei, 
Taiwan, Republic of China, 2 + 521-9321. 

UNITED KINGDOM: Texas Instruments Limited. 
Manton Lane, Bedford, MK41 7PA, England, 0234 
67466; St. James House, Wellington Road North, 
Stockport, SK4 2RT, England, 61 +442-7162. 
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